Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:Ledest:erlang
erlang
4122-megaco-Types-and-spec-for-megaco-call-3.patch
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File 4122-megaco-Types-and-spec-for-megaco-call-3.patch of Package erlang
From cdc4cbb5142c9ea5df9e8569822ca22f73995759 Mon Sep 17 00:00:00 2001 From: Micael Karlberg <bmk@erlang.org> Date: Tue, 19 Dec 2023 18:06:07 +0100 Subject: [PATCH 02/46] [megaco] Types and spec for megaco:call/3 Updates to document the megaco:call/3 function using spec and "proper" types. Required a whole bunch of type restructuring. Also, megaco doc did not use spec's before now, so that part had to be added. OTP-18920 --- lib/megaco/doc/specs/.gitignore | 1 + lib/megaco/doc/src/Makefile | 76 +++++- lib/megaco/doc/src/megaco.xml | 295 +++++++++++++++------ lib/megaco/doc/src/megaco_encoder.xml | 292 +++++++++++++++++++- lib/megaco/doc/src/megaco_user.xml | 38 ++- lib/megaco/doc/src/specs.xml | 6 + lib/megaco/src/app/megaco.erl | 71 ++++- lib/megaco/src/engine/megaco_encoder.erl | 47 +++- lib/megaco/src/engine/megaco_messenger.erl | 3 +- lib/megaco/src/engine/megaco_user.erl | 8 +- 10 files changed, 732 insertions(+), 105 deletions(-) create mode 100644 lib/megaco/doc/specs/.gitignore create mode 100644 lib/megaco/doc/src/specs.xml diff --git a/lib/megaco/doc/specs/.gitignore b/lib/megaco/doc/specs/.gitignore new file mode 100644 index 0000000000..322eebcb06 --- /dev/null +++ b/lib/megaco/doc/specs/.gitignore @@ -0,0 +1 @@ +specs_*.xml diff --git a/lib/megaco/doc/src/Makefile b/lib/megaco/doc/src/Makefile index 64bf4bd0ca..ff8f88c938 100644 --- a/lib/megaco/doc/src/Makefile +++ b/lib/megaco/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2000-2021. All Rights Reserved. +# Copyright Ericsson AB 2000-2023. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -36,8 +36,24 @@ include files.mk # ---------------------------------------------------- -XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \ - $(XML_PART_FILES) $(XML_CHAPTER_FILES) +XML_FILES = \ + $(BOOK_FILES) \ + $(XML_APPLICATION_FILES) \ + $(XML_REF3_FILES) \ + $(XML_PART_FILES) \ + $(XML_CHAPTER_FILES) + +# SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) +SPECS_FILES = \ + $(SPECDIR)/specs_megaco.xml \ + $(SPECDIR)/specs_megaco_encoder.xml \ + $(SPECDIR)/specs_megaco_user.xml +TOP_SPECS_FILE = specs.xml + +NO_CHUNKS = megaco_edist_compress.xml \ + megaco_transport.xml megaco_tcp.xml megaco_udp.xml \ + megaco_codec_meas.xml megaco_codec_mstone1.xml \ + megaco_codec_mstone2.xml megaco_codec_transform.xml STANDARD_DIR = ../standard STANDARDS = $(STANDARD_DIR)/rfc3525.txt \ @@ -45,9 +58,56 @@ STANDARDS = $(STANDARD_DIR)/rfc3525.txt \ $(STANDARD_DIR)/rfc4566.txt \ $(STANDARD_DIR)/implementors_guide_v10-13.pdf -NO_CHUNKS = - include $(ERL_TOP)/make/doc.mk +SPECS_FLAGS += -I../../src/app -I../../include -I../../../kernel/include + +$(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/app/%.erl $(TOP_SPECS_FILE) + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +# $(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/binary/%.erl $(TOP_SPECS_FILE) +# $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +$(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/engine/%.erl $(TOP_SPECS_FILE) + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +# $(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/flex/%.erl $(TOP_SPECS_FILE) +# $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +# $(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/tcp/%.erl $(TOP_SPECS_FILE) +# $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +# $(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/udp/%.erl $(TOP_SPECS_FILE) +# $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< + +# We need some fake rules for targets that does not actually have any specs... +$(SPECDIR)/specs_megaco_codec_meas.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_codec_meas +$(SPECDIR)/specs_megaco_codec_mstone1.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_codec_mstone1 +$(SPECDIR)/specs_megaco_codec_mstone2.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_codec_mstone2 +$(SPECDIR)/specs_megaco_codec_transform.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_codec_transform +$(SPECDIR)/specs_megaco_compress.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_edist_compress +#$(SPECDIR)/specs_megaco_encoder.xml: +# escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ +# -o$(dir $@) -module megaco_encoder +$(SPECDIR)/specs_megaco_flex_scanner.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_flex_scanner +$(SPECDIR)/specs_megaco_tcp.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_tcp +$(SPECDIR)/specs_megaco_transport.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_codec_transport +$(SPECDIR)/specs_megaco_udp.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module megaco_udp +#$(SPECDIR)/specs_megaco_user.xml: +# escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ +# -o$(dir $@) -module megaco_user $(HTMLDIR)/megaco_architecture.html: megaco_architecture.xml $(HTMLDIR)/megaco_codec_meas.html: megaco_codec_meas.xml diff --git a/lib/megaco/doc/src/megaco.xml b/lib/megaco/doc/src/megaco.xml index e44c061f48..882e77af6c 100644 --- a/lib/megaco/doc/src/megaco.xml +++ b/lib/megaco/doc/src/megaco.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2020</year> + <year>2000</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -38,10 +38,153 @@ <p>Interface module for the Megaco application</p> </description> + <datatypes> + <datatype> + <name name="mid"/> + <desc> + <p> + The Megaco Identifier. + </p> + </desc> + </datatype> + + <datatype> + <name name="action_request"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="action_reply"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="error_desc"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="transaction_reply"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="protocol_version"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="segment_no"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="conn_handle"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="megaco_timer"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="action_reqs"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="action_reps"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="send_option"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="send_handle"/> + <desc> + <p> + Opaque send handle whose contents is internal for the send module. + May be any term. + </p> + </desc> + </datatype> + + </datatypes> + <section> <title>DATA TYPES</title> <code type="none"><![CDATA[ -megaco_mid() = ip4Address() | ip6Address() | +mid() = ip4Address() | ip6Address() | domainName() | deviceName() | mtpAddress() ip4Address() = #'IP4Address'{} @@ -1454,91 +1597,73 @@ megaco_incr_timer() = #megaco_incr_timer{} </func> <func> - <name since="">call(ConnHandle, Actions, Options) -> {ProtocolVersion, UserReply}</name> + <name name="call" arity="3" clause_i="1" since=""/> <fsummary>Sends one or more transaction request(s) and waits for the reply</fsummary> - <type> - <v>ConnHandle = conn_handle()</v> - <v>Actions = action_reqs() | [action_reqs()]</v> - <v>action_reqs() = binary() | [action_request()]</v> - <v>Options = [send_option()]</v> - <v>send_option() = {request_timer, megaco_timer()} | {long_request_timer, megaco_timer()} | {send_handle, term()} | {protocol_version, integer()} | {call_proxy_gc_timeout, call_proxy_gc_timeout()}</v> - <v>ProtocolVersion = integer()</v> - <v>UserReply = user_reply() | [user_reply()]</v> - <v>user_reply() = success() | failure()</v> - <v>success() = {ok, result()} | {ok, result(), extra()}</v> - <v>result() = message_result() | segment_result()</v> - <v>message_result() = action_reps()</v> - <v>segment_result() = segments_ok()</v> - <v>failure() = {error, reason()} | {error, reason(), extra()}</v> - <v>reason() = message_reason() | segment_reason() | user_cancel_reason() | send_reason() | other_reason()</v> - <v>message_reason() = error_desc()</v> - <v>segment_reason() = {segment, segments_ok(), segments_err()} | {segment_timeout, missing_segments(), segments_ok(), segments_err()}</v> - <v>segments_ok() = [segment_ok()]</v> - <v>segment_ok() = {segment_no(), action_reps()}</v> - <v>segments_err() = [segment_err()]</v> - <v>segment_err() = {segment_no(), error_desc()}</v> - <v>missing_segments() = [segment_no()]</v> - <v>user_cancel_reason() = {user_cancel, reason_for_user_cancel()}</v> - <v>reason_for_user_cancel() = term()</v> - <v>send_reason() = send_cancelled_reason() | send_failed_reason()</v> - <v>send_cancelled_reason() = {send_message_cancelled, reason_for_send_cancel()}</v> - <v>reason_for_send_cancel() = term()</v> - <v>send_failed_reason() = {send_message_failed, reason_for_send_failure()}</v> - <v>reason_for_send_failure() = term()</v> - <v>other_reason() = {wrong_mid, WrongMid, RightMid, TR} | term()</v> - <v>WrongMid = mid()</v> - <v>RightMid = mid()</v> - <v>TR = transaction_reply()</v> - <v>action_reps() = [action_reply()]</v> - <v>call_proxy_gc_timeout() = integer() >= 0</v> - <v>extra() = term()</v> - </type> <desc> - <p>Sends one or more transaction request(s) and waits for the - reply.</p> - <p>When sending one transaction in a message, <c><![CDATA[Actions]]></c> should be - <c><![CDATA[action_reqs()]]></c> (<c><![CDATA[UserReply]]></c> will then be - <c><![CDATA[user_reply()]]></c>). When sending several transactions in a message, - <c><![CDATA[Actions]]></c> should be <c><![CDATA[[action_reqs()]]]></c> (<c><![CDATA[UserReply]]></c> - will then be <c><![CDATA[[user_reply()]]]></c>). Each element of the list is - part of one transaction.</p> - <p>For some of <em>our</em> codecs (not binary), it is also possible - to pre-encode the actions, in which case <c><![CDATA[Actions]]></c> will be - either a <c><![CDATA[binary()]]></c> or <c><![CDATA[[binary()]]]></c>.</p> - <p>The function returns when the reply arrives, when the - request timer eventually times out or when the outstanding - requests are explicitly cancelled.</p> - <p>The default values of the send options are obtained by - <c><![CDATA[megaco:conn_info(ConnHandle, Item)]]></c>. But the send options - above, may explicitly be overridden.</p> - <p>The <c><![CDATA[ProtocolVersion]]></c> version is the version actually encoded - in the reply message.</p> - <p>At <c><![CDATA[success()]]></c>, the <c><![CDATA[UserReply]]></c> contains a list of - 'ActionReply' records possibly containing error indications.</p> - <p>A <c><![CDATA[message_error()]]></c>, indicates that the remote user has - replied with an explicit transactionError.</p> - <p>A <c><![CDATA[user_cancel_error()]]></c>, indicates that the request has been - canceled by the user. <c><![CDATA[reason_for_user_cancel()]]></c> is the reason - given in the call to the <seeerl marker="#cancel">cancel</seeerl> - function. </p> - <p>A <c><![CDATA[send_error()]]></c>, indicates that the send function of the - megaco transport callback module failed to send the request. - There are two separate cases: <c><![CDATA[send_cancelled_reason()]]></c> and - <c><![CDATA[send_failed_reason()]]></c>. - The first is the result of the send function returning - <c><![CDATA[{cancel, Reason}]]></c> and the second is some other kind of - erroneous return value. See the - <seeerl marker="megaco_transport#send_message">send_message</seeerl> - function for more info. </p> - <p>An <c><![CDATA[other_error()]]></c>, indicates some other error such as - timeout.</p> - - <p>For more info about the <c>extra()</c> part of the - result, see the - <seeerl marker="megaco_user#extra_argument">note</seeerl> - in the user callback module documentation. </p> - - + <p>Sends one or more transaction request(s) and waits for the reply.</p> + + <p>When sending one transaction in a message, + <c><![CDATA[ActionRequests]]></c> should be + <c><![CDATA[action_reqs()]]></c> (the reply + will then be <c><![CDATA[UserReply]]></c>). + When sending several transactions in a message, + <c><![CDATA[ActionRequests]]></c> should be + <c><![CDATA[[action_reqs()]]]></c> (the reply + will then be <c><![CDATA[[UserReply]]]></c>). + Each element of the list is + part of one transaction.</p> + + <p>For some of <em>our</em> codecs (not binary), it is also possible + to pre-encode the actions, in which case + <c><![CDATA[ActionRequests]]></c> + will be either a <c><![CDATA[binary()]]></c> or + <c><![CDATA[[binary()]]]></c>.</p> + + <p>The function returns when the reply arrives, when the + request timer eventually times out or when the outstanding + requests are explicitly cancelled.</p> + + <p>The default values of the send options are obtained by + <c><![CDATA[megaco:conn_info(ConnHandle, Item)]]></c>. + But the send options above, may explicitly be overridden.</p> + + <p>The <c><![CDATA[ProtocolVersion]]></c> version is the version + actually encoded in the reply message.</p> + + <p>At <c><![CDATA[Success]]></c>, the <c><![CDATA[UserReply]]></c> + contains a list of 'ActionReply' records possibly containing + error indications.</p> + + <p>A <c><![CDATA[Failure]]></c>, indicates that the remote user has + replied with an explicit transactionError.</p> + + <p>A <c><![CDATA[UserCancelReason]]></c>, indicates that the + request has been canceled by the user. + <c><![CDATA[ReasonForUserCancel]]></c> is the reason + given in the call to the <seeerl marker="#cancel">cancel</seeerl> + function. </p> + + <p>A send error (<c><![CDATA[SendReason]]></c>), + indicates that the send function of the + megaco transport callback module failed to send the request. + There are two separate cases: + <c><![CDATA[SendCancelledReason]]></c> and + <c><![CDATA[SendFailedReason]]></c>. + The first is the result of the send function returning + <c><![CDATA[{cancel, Reason}]]></c> and the second is some other + kind of erroneous return value. + See the + <seeerl marker="megaco_transport#send_message">send_message</seeerl> + function for more info. </p> + + <p>An <c><![CDATA[OtherReason]]></c>, indicates some other + error such as timeout.</p> + + <p>For more info about the 'extra' part of the result + (<c><![CDATA[SuccessExtra]]></c> and <c><![CDATA[ErrorExtra]]></c>), + see the + <seeerl marker="megaco_user#extra_argument">note</seeerl> + in the user callback module documentation. </p> <marker id="cast"></marker> </desc> diff --git a/lib/megaco/doc/src/megaco_encoder.xml b/lib/megaco/doc/src/megaco_encoder.xml index e8062ade5a..708a9ddc73 100644 --- a/lib/megaco/doc/src/megaco_encoder.xml +++ b/lib/megaco/doc/src/megaco_encoder.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2003</year><year>2020</year> + <year>2003</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -40,6 +40,296 @@ </description> + <datatypes> + <datatype> + <name name="octet"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="octet_string"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="alpha"/> + <desc> + <p> + Alpha Numeric characters: + <code> + A..Z | a..z + </code> + </p> + </desc> + </datatype> + + <datatype> + <name name="digit"/> + <desc> + <p> + Decimal digits: + <code> + 0..9 + </code> + </p> + </desc> + </datatype> + + <datatype> + <name name="protocol_version"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="segment_no"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="ip4Address"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="ip6Address"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="domainName"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="deviceName"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="pathName"/> + <desc> + <p> + There is no way to properly express this type in the Erlang + type system, so this is the best we can do. + The minimum length is 1 and the maximum length is 64. + </p> + <p> + Here is the ABNF (copied from the megaco standard) to + fill in the blanks: + <code> + # Total length of pathNAME must not exceed 64 chars. + pathNAME = ["*"] NAME *("/" / "*"/ ALPHA / DIGIT /"_" / "$" ) + ["@" pathDomainName ] + + # ABNF allows two or more consecutive "." + # although it is meaningless in a path domain name. + pathDomainName = (ALPHA / DIGIT / "*" ) + *63(ALPHA / DIGIT / "-" / "*" / ".") + + NAME = ALPHA *63(ALPHA / DIGIT / "_" ) + </code> + </p> + </desc> + </datatype> + + <datatype> + <name name="mtpAddress"/> + <desc> + <p> + There is no way to properly express this type in the Erlang + type system, so this is the best we can do. + </p> + <p> + A proper definition would be: + <code> + -type mtpAddress() :: octet_string(2..4). + </code> + </p> + </desc> + </datatype> + + <datatype> + <name name="megaco_message"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="transaction"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="transaction_request"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="transaction_pending"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="transaction_reply"/> + <desc> + <p> + The problem with TransactionReply is that its definition depend + on which version of the protocol we are using. As of version 3, + it has two more fields. + </p> + </desc> + </datatype> + + <datatype> + <name name="transaction_response_ack"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="transaction_ack"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="segment_reply"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="action_request"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="action_reply"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="command_request"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="error_desc"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + </datatypes> + <section> <title>DATA TYPES</title> <note> diff --git a/lib/megaco/doc/src/megaco_user.xml b/lib/megaco/doc/src/megaco_user.xml index fc092a3214..381f6edadb 100644 --- a/lib/megaco/doc/src/megaco_user.xml +++ b/lib/megaco/doc/src/megaco_user.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2020</year> + <year>2000</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -120,6 +120,42 @@ </description> + <datatypes> + <datatype> + <name name="receive_handle"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="conn_handle"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + <datatype> + <name name="megaco_timer"/> + <!-- + <desc> + <p> + TBD. + </p> + </desc> + --> + </datatype> + + </datatypes> + <section> <title>DATA TYPES</title> <code type="none"><![CDATA[ diff --git a/lib/megaco/doc/src/specs.xml b/lib/megaco/doc/src/specs.xml new file mode 100644 index 0000000000..a36a772166 --- /dev/null +++ b/lib/megaco/doc/src/specs.xml @@ -0,0 +1,6 @@ +<?xml version="1.0" encoding="utf-8" ?> +<specs xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="../specs/specs_megaco.xml"/> + <xi:include href="../specs/specs_megaco_encoder.xml"/> + <xi:include href="../specs/specs_megaco_user.xml"/> +</specs> diff --git a/lib/megaco/src/app/megaco.erl b/lib/megaco/src/app/megaco.erl index d0816b1dd0..6db673f2fa 100644 --- a/lib/megaco/src/app/megaco.erl +++ b/lib/megaco/src/app/megaco.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1999-2022. All Rights Reserved. +%% Copyright Ericsson AB 1999-2023. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -99,11 +99,43 @@ ]). -export_type([ - void/0 + void/0, + + mid/0, + conn_handle/0, + action_request/0, + action_reply/0, + error_desc/0, + transaction_reply/0, + protocol_version/0 ]). -type void() :: term(). +-type mid() :: megaco_encoder:ip4Address() | + megaco_encoder:ip6Address() | + megaco_encoder:domainName() | + megaco_encoder:deviceName() | + megaco_encoder:mtpAddress(). +-type action_request() :: megaco_encoder:action_request(). +-type action_reply() :: megaco_encoder:action_reply(). +-type error_desc() :: megaco_encoder:error_desc(). +-type transaction_reply() :: megaco_encoder:transaction_reply(). +-type protocol_version() :: megaco_encoder:protocol_version(). +-type segment_no() :: megaco_encoder:segment_no(). +-type conn_handle() :: megaco_user:conn_handle(). +-type megaco_timer() :: megaco_user:megaco_timer(). + +-type action_reqs() :: binary() | [action_request()]. +-type action_reps() :: [action_reply()]. +-type send_option() :: {request_timer, megaco_timer()} | + {long_request_timer, megaco_timer()} | + {send_handle, send_handle()} | + {protocol_version, protocol_version()} | + {call_proxy_gc_timeout, non_neg_integer()}. +-type send_handle() :: term(). + + -include("megaco_internal.hrl"). @@ -282,6 +314,41 @@ disconnect(ConnHandle, Reason) -> %% Sends a transaction request and waits for a reply %%----------------------------------------------------------------- +-spec call(ConnHandle, ActionRequests, Options) -> + {ProtocolVersion, UserReply | [UserReply]} when + ConnHandle :: conn_handle(), + ActionRequests :: action_reqs() | [action_reqs()], + Options :: [send_option()], + ProtocolVersion :: protocol_version(), + UserReply :: Success | Failure, + Success :: {ok, Result} | {ok, Result, SuccessExtra}, + Result :: MessageResult | SegmentResult, + MessageResult :: action_reps(), + SegmentResult :: SegmentsOk, + SegmentsOk :: [{segment_no(), action_reps()}], + Failure :: {error, Reason} | {error, Reason, ErrorExtra}, + Reason :: MessageReason | SegmentReason | + UserCancelReason | SendReason | OtherReason, + MessageReason :: error_desc(), + SegmentReason :: {segment, SegmentsOk, SegmentsErr} | + {segment_timeout, + MissingSegments, + SegmentsOk, + SegmentsErr}, + SegmentsErr :: {segment_no(), error_desc()}, + MissingSegments :: [segment_no()], + UserCancelReason :: {user_cancel, ReasonForUserCancel}, + ReasonForUserCancel :: term(), + SendReason :: SendCancelledReason | SendFailedReason, + SendCancelledReason :: {send_message_cancelled, term()}, + SendFailedReason :: {send_message_failed, term()}, + OtherReason :: {wrong_mid, + WrongMid :: mid(), + RightMid :: mid(), + transaction_reply()} | term(), + SuccessExtra :: term(), + ErrorExtra :: term(). + call(ConnHandle, ActionRequests, Options) -> megaco_messenger:call(ConnHandle, ActionRequests, Options). diff --git a/lib/megaco/src/engine/megaco_encoder.erl b/lib/megaco/src/engine/megaco_encoder.erl index dd5a3458fc..41a394dca4 100644 --- a/lib/megaco/src/engine/megaco_encoder.erl +++ b/lib/megaco/src/engine/megaco_encoder.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2003-2019. All Rights Reserved. +%% Copyright Ericsson AB 2003-2023. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -25,6 +25,22 @@ -module(megaco_encoder). +-export_type([ + octet/0, + octet_string/0, + alpha/0, + digit/0 + ]). + +-export_type([ + ip4Address/0, + ip6Address/0, + domainName/0, + deviceName/0, + pathName/0, + mtpAddress/0 + ]). + -export_type([ protocol_version/0, segment_no/0, @@ -45,8 +61,33 @@ -include("megaco_message_internal.hrl"). --type protocol_version() :: integer(). --type segment_no() :: integer(). + +-type octet() :: 16#00..16#FF. % 0..255 +-type octet_string() :: [octet()]. +-type alpha() :: 16#41..16#5A | 16#61..16#7A. % A..Z | a..z +-type digit() :: 16#30..16#39. % 0..9 + +-type ip4Address() :: #'IP4Address'{}. +-type ip6Address() :: #'IP6Address'{}. +-type domainName() :: #'DomainName'{}. +-type deviceName() :: pathName(). +%% ia5String(1..64) +%% Total length of pathNAME must not exceed 64 chars. +%% pathNAME = ["*"] NAME *("/" / "*"/ ALPHA / DIGIT /"_" / "$" ) +%% ["@" pathDomainName ] +%% +%% ABNF allows two or more consecutive "." although it is meaningless +%% in a path domain name. +%% pathDomainName = (ALPHA / DIGIT / "*" ) +%% *63(ALPHA / DIGIT / "-" / "*" / ".") +%% +%% NAME = ALPHA *63(ALPHA / DIGIT / "_" ) +-type pathName() :: [$* | alpha() | digit() | $_ | $/ | $$ | $@ | $- | $.]. +-type mtpAddress() :: octet_string(). % octet_string(2..4). + +-type protocol_version() :: pos_integer(). +-type segment_no() :: 0..65535. + -type megaco_message() :: #'MegacoMessage'{}. -type transaction() :: {transactionRequest, transaction_request()} | {transactionPending, transaction_reply()} | diff --git a/lib/megaco/src/engine/megaco_messenger.erl b/lib/megaco/src/engine/megaco_messenger.erl index dfb10dc869..366a52bfc8 100644 --- a/lib/megaco/src/engine/megaco_messenger.erl +++ b/lib/megaco/src/engine/megaco_messenger.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1999-2022. All Rights Reserved. +%% Copyright Ericsson AB 1999-2023. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -74,6 +74,7 @@ -include("megaco_message_internal.hrl"). -include_lib("megaco/src/app/megaco_internal.hrl"). + %% N.B. Update cancel/1 with '_' when a new field is added -record(request, {trans_id, diff --git a/lib/megaco/src/engine/megaco_user.erl b/lib/megaco/src/engine/megaco_user.erl index 47fb1a119d..94554900c9 100644 --- a/lib/megaco/src/engine/megaco_user.erl +++ b/lib/megaco/src/engine/megaco_user.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2019-2019. All Rights Reserved. +%% Copyright Ericsson AB 2019-2023. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -22,9 +22,9 @@ %%------------------------------------------------------------------------- %% Purpose: Megaco user behaviour module %% -%% This callback functions are the default! Its possible for the user to -%% provide a arbitrary number of "extra" arguments via the user_args -%% config option. +%% These callback functions are the default! +%% Its possible for the user to provide a arbitrary number of "extra" +%% arguments via the user_args config option. %% So, for instance, the handle_connect/2 could instead become %% handle_connect/4 if the user sets the user_args option to [foo, bar]. %% This means that its impossible to define a proper behaviour. -- 2.35.3
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
