File 4128-megaco-Types-and-spec-for-megaco-connect-4... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 4128-megaco-Types-and-spec-for-megaco-connect-4-5.patch of Package erlang

From ddd418edaa95f9685d5490cfd474b19bd158e1e0 Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Fri, 22 Dec 2023 10:22:59 +0100
Subject: [PATCH 08/46] [megaco] Types and spec for megaco:connect/4,5

OTP-18920
---
 lib/megaco/doc/src/megaco.xml | 118 +++++++++++++++++++---------------
 lib/megaco/src/app/megaco.erl |  33 ++++++++++
 2 files changed, 98 insertions(+), 53 deletions(-)

diff --git a/lib/megaco/doc/src/megaco.xml b/lib/megaco/doc/src/megaco.xml
index e6437c49d1..6791dcd112 100644
--- a/lib/megaco/doc/src/megaco.xml
+++ b/lib/megaco/doc/src/megaco.xml
@@ -114,6 +114,17 @@
 -->
 </datatype>
 
+ <datatype>
+ <name name="receive_handle"/>
+ 
+ </datatype>
+
 <datatype>
 <name name="conn_handle"/>
 <!--
@@ -1514,52 +1525,48 @@ megaco_incr_timer() = #megaco_incr_timer{}
 </func>
 
 <func>
- <name since="">connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid) -> {ok, ConnHandle} | {error, Reason}</name>
- <name since="">connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid, Extra) -> {ok, ConnHandle} | {error, Reason}</name>
+ <name name="connect" arity="4" clause_i="1" since=""/>
+ <name name="connect" arity="5" clause_i="1" since=""/>
 <fsummary>Establish a "virtual" connection</fsummary>
- <type>
- <v>ReceiveHandle = #megaco_receive_handle{}</v>
- <v>RemoteMid = preliminary_mid | megaco_mid()</v>
- <v>SendHandle = term()</v>
- <v>ControlPid = pid()</v>
- <v>ConnHandle = #megaco_conn_handle{}</v>
- <v>Reason = connect_reason() | handle_connect_reason() | term()</v>
-	<v>connect_reason() = {no_such_user, LocalMid} | {already_connected, ConnHandle} | term()</v>
-	<v>handle_connect_error() = {connection_refused, ConnData, ErrorInfo} | term()</v>
-	<v>LocalMid = megaco_mid()</v>
-	<v>ConnData = term()</v>
-	<v>ErrorInfo = term()</v>
- <v>Extra = term()</v>
- </type>
 <desc>
 Establish a "virtual" connection
- Activates a connection to a remote user. When this is done
- the connection can be used to send messages (with
- SendMod:send_message/2). The ControlPid is the identifier
- of a process that controls the connection. That process will
- be supervised and if it dies, this will be detected and the
- UserMod:handle_disconnect/2 callback function will be
- invoked. See the megaco_user module for more info about the
- callback arguments. The connection may also explicitly be
- deactivated by invoking megaco:disconnect/2.
- The ControlPid may be the identity of a process residing on
- another Erlang node. This is useful when you want to
- distribute a user over several Erlang nodes. In such a case
- one of the nodes has the physical connection. When a user
- residing on one of the other nodes needs to send a request
- (with megaco:call/3 or megaco:cast/3), the message will
- encoded on the originating Erlang node, and then be
- forwarded to the node with the physical connection. When the
- reply arrives, it will be forwarded back to the originator.
- The distributed connection may explicitly be deactivated by
- a local call to megaco:disconnect/2 or implicitly when
- the physical connection is deactivated (with megaco:disconnect/2,
- killing the controlling process, halting the other node, ...).
- The call of this function will trigger the callback
- function UserMod:handle_connect/2 to be invoked. See the
- megaco_user module for more info about the callback
- arguments.
- A connection may be established in several ways:
+
+	Activates a connection to a remote user. When this is done
+	the connection can be used to send messages (with
+	<c><![CDATA[SendMod:send_message/2]]></c>).
+	The <c><![CDATA[ControlPid]]></c> is the identifier
+	of a process that controls the connection. That process will
+	be supervised and if it dies, this will be detected and the
+	<c><![CDATA[UserMod:handle_disconnect/2]]></c> callback function
+	will be
+	invoked. See the megaco_user module for more info about the
+	callback arguments. The connection may also explicitly be
+	deactivated by invoking
+	<c><![CDATA[megaco:disconnect/2]]></c>.
+
+	The <c><![CDATA[ControlPid]]></c> may be the identity of a
+	process residing on
+	another Erlang node. This is useful when you want to
+	distribute a user over several Erlang nodes. In such a case
+	one of the nodes has the physical connection. When a user
+	residing on one of the other nodes needs to send a request
+	(with <c><![CDATA[megaco:call/3]]></c> or
+	<c><![CDATA[megaco:cast/3]]></c>), the message will
+	encoded on the originating Erlang node, and then be
+	forwarded to the node with the physical connection. When the
+	reply arrives, it will be forwarded back to the originator.
+	The distributed connection may explicitly be deactivated by
+	a local call to <c><![CDATA[megaco:disconnect/2]]></c> or
+	implicitly when the physical connection is deactivated
+	(with <c><![CDATA[megaco:disconnect/2]]></c>,
+	killing the controlling process, halting the other node, ...).
+
+	The call of this function will trigger the callback
+	function <c><![CDATA[UserMod:handle_connect/2]]></c> to be invoked.
+	See the megaco_user module for more info about the callback
+	arguments.
+
+	A connection may be established in several ways:
 <taglist>
 <tag><c><![CDATA[provisioned MID]]></c></tag>
 <item>
@@ -1577,8 +1584,9 @@ megaco_incr_timer() = #megaco_incr_timer{}
 message header and automatically upgrade the connection
 to be a "normal" connection. By using this method of
 establishing the connection, the callback function
- UserMod:handle_connect/2 to be invoked twice. First with
- a ConnHandle with the remote_mid-field set to
+	 <c><![CDATA[UserMod:handle_connect/2]]></c> to be invoked twice.
+	 First with
+ a <c><![CDATA[ConnHandle]]></c> with the remote_mid-field set to
 preliminary_mid, and then when the connection upgrade is
 done with the remote_mid-field set to the actual MID of
 the MGC.
@@ -1595,12 +1603,13 @@ megaco_incr_timer() = #megaco_incr_timer{}
 When a user (MG/MGC) is distributed over several nodes,
 it is required that the node hosting the connection
 already has activated the connection and that it is
- in the "normal" state. The RemoteMid must be a real
- Megaco MID and not a preliminary_mid.
+	 in the "normal" state. The <c><![CDATA[RemoteMid]]></c>
+	 must be a real
+ Megaco MID and not a <c><![CDATA[preliminary_mid]]></c>.
 </item>
 </taglist>
 An initial megaco_receive_handle record may be obtained
- with megaco:user_info(UserMid, receive_handle)
+	with <c><![CDATA[megaco:user_info(UserMid, receive_handle)]]></c>
 The send handle is provided by the preferred transport
 module, e.g. megaco_tcp, megaco_udp. Read the documentation
 about each transport module about the details.
@@ -1609,17 +1618,20 @@ megaco_incr_timer() = #megaco_incr_timer{}
 <c>connection setup</c> and then by calling the user 
 <seeerl marker="megaco_user#connect">handle_connect</seeerl> 
 callback function. The first step could result in 
- an error with <c>Reason = connect_reason()</c> and the second 
- an error with <c>Reason = handle_connect_reason()</c>: 
+	 an error with
+	 <c><![CDATA[Reason = ConnectReason]]></c>
+	 and the second 
+	 an error with
+	<c><![CDATA[Reason = HandleConnectReason]]></c>: 
 
 	<taglist>
-	 <tag><c>connect_reason()</c></tag>
+	 <tag><c>ConnectReason</c></tag>
 	 <item>
 	 An error with this reason is generated by the 
- megaco application itself.
+	 megaco application itself.
 	 </item>
 
-	 <tag><c>handle_connect_reason()</c></tag>
+	 <tag><c>HandleConnectReason</c></tag>
 	 <item>
 	 An error with this reason is caused by the user 
 <seeerl marker="megaco_user#connect">handle_connect</seeerl> 
diff --git a/lib/megaco/src/app/megaco.erl b/lib/megaco/src/app/megaco.erl
index ab870d0d13..b97c5ad377 100644
--- a/lib/megaco/src/app/megaco.erl
+++ b/lib/megaco/src/app/megaco.erl
@@ -102,6 +102,7 @@
 void/0,
 
 mid/0,
+ receive_handle/0,
 conn_handle/0,
 action_request/0,
 action_reply/0,
@@ -123,6 +124,7 @@
 -type transaction_reply() :: megaco_encoder:transaction_reply().
 -type protocol_version() :: megaco_encoder:protocol_version().
 -type segment_no() :: megaco_encoder:segment_no().
+-type receive_handle() :: megaco_user:receive_handle().
 -type conn_handle() :: megaco_user:conn_handle().
 -type megaco_timer() :: megaco_user:megaco_timer().
 -type transaction_id() :: pos_integer().
@@ -355,9 +357,40 @@ system_info(Item) ->
 %% Establish a "virtual" connection
 %%-----------------------------------------------------------------
 
+-spec connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid) ->
+ {ok, ConnHandle} | {error, Reason} when
+ ReceiveHandle :: receive_handle(),
+ RemoteMid :: preliminary_mid | mid(),
+ SendHandle :: send_handle(),
+ ControlPid :: pid(),
+ ConnHandle :: conn_handle(),
+ Reason :: ConnectReason | HandleConnectReason | term(),
+ ConnectReason :: {no_such_user, LocalMid} |
+ {already_connected, ConnHandle} | term(),
+ LocalMid :: mid(),
+ HandleConnectReason :: {connection_refused, ConnData, ErrorInfo} | term(),
+ ConnData :: term(),
+ ErrorInfo :: term(). 
+
 connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid) ->
 megaco_messenger:connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid).
 
+-spec connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid, Extra) ->
+ {ok, ConnHandle} | {error, Reason} when
+ ReceiveHandle :: receive_handle(),
+ RemoteMid :: preliminary_mid | mid(),
+ SendHandle :: send_handle(),
+ ControlPid :: pid(),
+ Extra :: term(),
+ ConnHandle :: conn_handle(),
+ Reason :: ConnectReason | HandleConnectReason | term(),
+ ConnectReason :: {no_such_user, LocalMid} |
+ {already_connected, ConnHandle} | term(),
+ LocalMid :: mid(),
+ HandleConnectReason :: {connection_refused, ConnData, ErrorInfo} | term(),
+ ConnData :: term(),
+ ErrorInfo :: term(). 
+
 connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid, Extra) 
 when (Extra =/= ?default_user_callback_extra) ->
 megaco_messenger:connect(ReceiveHandle, RemoteMid, SendHandle, 
-- 
2.35.3

Places

File 4128-megaco-Types-and-spec-for-megaco-connect-4-5.patch of Package erlang

Places