Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:Ledest:erlang:26
erlang
2049-megaco-Types-and-spec-for-megaco-userinfo-...
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File 2049-megaco-Types-and-spec-for-megaco-userinfo-1-2.patch of Package erlang
From b20f4a572b46833c109da8878005db623b122624 Mon Sep 17 00:00:00 2001 From: Micael Karlberg <bmk@erlang.org> Date: Mon, 8 Jan 2024 11:01:57 +0100 Subject: [PATCH 39/46] [megaco] Types and spec for megaco:userinfo/1,2 OTP-18920 --- lib/megaco/doc/src/megaco.xml | 509 ++-------------------------------- lib/megaco/src/app/megaco.erl | 29 +- 2 files changed, 48 insertions(+), 490 deletions(-) diff --git a/lib/megaco/doc/src/megaco.xml b/lib/megaco/doc/src/megaco.xml index 74c5c7b309..cfde6569ad 100644 --- a/lib/megaco/doc/src/megaco.xml +++ b/lib/megaco/doc/src/megaco.xml @@ -683,7 +683,7 @@ <p>Default reply data. </p> <p>Value type: - <seetype marker="erlang#gterm">term()</seetype></p> + <seetype marker="erlang#term">term()</seetype></p> <p>Defaults to <c><![CDATA[undefined]]></c>.</p> <!-- <marker id="ci_threaded"></marker> --> @@ -1936,504 +1936,37 @@ megaco_incr_timer() = #megaco_incr_timer{} <p>Requires that the user does not have any active connection.</p> <marker id="user_info"></marker> + <marker id="user_info_11"></marker> + <marker id="user_info_23"></marker> </desc> </func> <func> - <name since="">user_info(UserMid) -> [{Item, Value}]</name> - <name since="">user_info(UserMid, Item) -> Value | exit(Reason)</name> + <name name="user_info" arity="1" clause_i="1" since=""/> + <name name="user_info" arity="2" clause_i="3" since=""/> <fsummary>Lookup user information</fsummary> - <type> - <v>Handle = user_info_handle()</v> - <v>UserMid = megaco_mid() </v> - <v>Item = user_info_item()</v> - <v>Value = user_info_value()</v> - <v>Reason = term()</v> - </type> <desc> <p>Lookup user information</p> - <p>The following Item's are valid:</p> - <marker id="ui_connections"></marker> - <taglist> - <tag><c><![CDATA[connections]]></c></tag> - <item> - <p>Lists all active connections for this user. Returns a - list of megaco_conn_handle records.</p> - <marker id="ui_receive_handle"></marker> - </item> - - <tag><c><![CDATA[receive_handle]]></c></tag> - <item> - <p>Construct a megaco_receive_handle record from user config</p> - - <marker id="ui_trans_id"></marker> - </item> - - <tag><c><![CDATA[trans_id]]></c></tag> - <item> - <p>Current transaction id. </p> - <p>A positive integer or the atom - <c><![CDATA[undefined_serial]]></c> (in case no messages has been sent).</p> - - <marker id="ui_min_trans_id"></marker> - </item> - - <tag><c><![CDATA[min_trans_id]]></c></tag> - <item> - <p>First trans id. </p> - <p>A positive integer, defaults to 1.</p> - - <marker id="ui_max_trans_id"></marker> - </item> - - <tag><c><![CDATA[max_trans_id]]></c></tag> - <item> - <p>Last trans id. </p> - <p>A positive integer or <c><![CDATA[infinity]]></c>, - defaults to <c><![CDATA[infinity]]></c>.</p> - - <marker id="ui_request_timer"></marker> - </item> - - <tag><c><![CDATA[request_timer]]></c></tag> - <item> - <p>Wait for reply. </p> - <p>The timer is cancelled when a reply is received. </p> - <p>When a pending message is received, the timer is - cancelled and the <c><![CDATA[long_request_timer]]></c> is started instead - (see below). No resends will be performed from this point - (since we now know that the other side has received the - request). </p> - <p>When the timer reaches an intermediate expire, the request - is resent and the timer is restarted. </p> - <p>When the timer reaches the final expire, either the function - <c><![CDATA[megaco:call]]></c> will return with <c><![CDATA[{error, timeout}]]></c> - or the callback function <c><![CDATA[handle_trans_reply]]></c> will be - called with <c><![CDATA[UserReply = {error, timeout}]]></c> (if - <c><![CDATA[megaco:cast]]></c> was used).</p> - <p>A Megaco Timer (see explanation above), - defaults to <c><![CDATA[#megaco_incr_timer{}]]></c>.</p> - - <marker id="ui_long_request_timer"></marker> - </item> - - <tag><c><![CDATA[long_request_timer]]></c></tag> - <item> - <p>Wait for reply after having received a pending message. </p> - <p>When the timer reaches an intermediate expire, the timer - is restarted. </p> - <p>When a pending message is received, and the - <c><![CDATA[long_request_timer]]></c> - is <em>not</em> "on its final leg", the timer will be - restarted, and, if <c><![CDATA[long_request_resend = true]]></c>, the - request will be re-sent. </p> - <p>A Megaco Timer (see explanation above), - defaults to <c><![CDATA[60 seconds]]></c>.</p> - - <marker id="ui_long_request_resend"></marker> - </item> - - <tag><c><![CDATA[long_request_resend]]></c></tag> - <item> - <p>This option indicates weather the request should be - resent until the reply is received, - <em>even</em> though a pending message has been received. </p> - <p>Normally, after a pending message has been received, - the request is not resent - (since a pending message is an indication that the - request has been received). But since the reply (to the - request) can be lost, this behaviour has its values.</p> - <p>It is of course pointless to set this value to <em>true</em> - unless the <c><![CDATA[long_request_timer]]></c> (see above) is also set - to an incremental timer (<c><![CDATA[#megaco_incr_timer{}]]></c>). </p> - <p>A <c><![CDATA[boolean]]></c>, - defaults to <c><![CDATA[false]]></c>.</p> - - <marker id="ui_reply_timer"></marker> - </item> - - <tag><c><![CDATA[reply_timer]]></c></tag> - <item> - <p>Wait for an ack. </p> - <p>When a request is received, some info - related to the reply is store internally (e.g. the - binary of the reply). This info will live until either - an ack is received or this timer expires. For instance, - if the same request is received again (e.g. a request - with the same transaction id), the (stored) reply will - be (re-) sent automatically by megaco.</p> - <p>If the timer is of type <c><![CDATA[#megaco_incr_timer{}]]></c>, - then for each intermediate timout, the reply will be resent - (this is valid until the ack is received or - the timer expires). </p> - <p>A Megaco Timer (see explanation above), defaults to 30000.</p> - - <marker id="ui_request_keep_alive_timeout"></marker> - </item> - - <tag><c><![CDATA[request_keep_alive_timeout]]></c></tag> - <item> - <p>Specifies the timeout time for the request-keep-alive timer. </p> - <p>This timer is started when the <em>first</em> reply to an asynchronous - request (issued using the - <seeerl marker="megaco#cast">megaco:cast/3</seeerl> function) - arrives. As long as this timer is running, replies will - be delivered via the - <seeerl marker="megaco_user#trans_reply">handle_trans_reply/4,5</seeerl> - callback function, with their "arrival number" - (see <c><![CDATA[UserReply]]></c> of the - <seeerl marker="megaco_user#trans_reply">handle_trans_reply/4,5</seeerl> - callback function). </p> - <p>Replies arriving after the timer has expired, will be - delivered using the - <seeerl marker="megaco_user#unexpected_trans">handle_unexpected_trans/3,4</seeerl> - callback function. </p> - <p>The timeout time can have the values: - <c><![CDATA[plain | integer() >= 0]]></c>. </p> - <p>Defaults to <c><![CDATA[plain]]></c>.</p> - - <marker id="ui_call_proxy_gc_timeout"></marker> - </item> - - <tag><c><![CDATA[call_proxy_gc_timeout]]></c></tag> - <item> - <p>Timeout time for the call proxy. </p> - <p>When a request is sent using the - <seeerl marker="megaco#call">call/3</seeerl> function, - a proxy process is started to handle - all replies. When the reply has been received and delivered - to the user, the proxy process continue to exist for as long - as this option specifies. Any received messages, is passed on - to the user via the - <seeerl marker="megaco_user#handle_unexpected_trans">handle_unexpected_trans</seeerl> - callback function. </p> - <p>The timeout time is in milliseconds. A value of 0 (zero) means - that the proxy process will exit directly after the reply has - been delivered. </p> - <p>An integer >= 0, defaults to 5000 (= 5 seconds).</p> - - <marker id="ui_auto_ack"></marker> - </item> - - <tag><c><![CDATA[auto_ack]]></c></tag> - <item> - <p>Automatic send transaction ack when the transaction - reply has been received (see <c><![CDATA[trans_ack]]></c> below). </p> - <p>This is used for <em>three-way-handshake</em>.</p> - <p>A <c><![CDATA[boolean]]></c>, defaults to <c><![CDATA[false]]></c>.</p> - - <marker id="ui_trans_ack"></marker> - </item> - - <tag><c><![CDATA[trans_ack]]></c></tag> - <item> - <p>Shall ack's be accumulated or not. </p> - <p>This property is only valid if <c><![CDATA[auto_ack]]></c> is true.</p> - <p>If <c><![CDATA[auto_ack]]></c> is true, then if <c><![CDATA[trans_ack]]></c> is - <c><![CDATA[false]]></c>, ack's will be sent immediately. - If <c><![CDATA[trans_ack]]></c> is <c><![CDATA[true]]></c>, then - ack's will instead be sent to the transaction - sender process for accumulation and later sending - (see <c><![CDATA[trans_ack_maxcount]]></c>, <c><![CDATA[trans_req_maxcount]]></c>, - <c><![CDATA[trans_req_maxsize]]></c>, <c><![CDATA[trans_ack_maxcount]]></c> and - <c><![CDATA[trans_timer]]></c>). </p> - <p>See also <seeguide marker="megaco_run#transaction_sender">transaction sender</seeguide> for more info.</p> - <p>An <c><![CDATA[boolean]]></c>, defaults to <c><![CDATA[false]]></c>.</p> - - <marker id="ui_trans_ack_maxcount"></marker> - </item> - - <tag><c><![CDATA[trans_ack_maxcount]]></c></tag> - <item> - <p>Maximum number of accumulated ack's. At most this many ack's - will be accumulated by the transaction sender (if started and - configured to accumulate ack's).</p> - <p>See also <seeguide marker="megaco_run#transaction_sender">transaction sender</seeguide> for more info. </p> - <p>An <c><![CDATA[integer]]></c>, defaults to 10.</p> - - <marker id="ui_trans_req"></marker> - </item> - - <tag><c><![CDATA[trans_req]]></c></tag> - <item> - <p>Shall requests be accumulated or not. </p> - <p>If <c><![CDATA[trans_req]]></c> is <c><![CDATA[false]]></c>, then request(s) - will be sent immediately (in its own message).</p> - <p>If <c><![CDATA[trans_req]]></c> is true, then request(s) will - instead be sent to the transaction sender process for - accumulation and later sending - (see <c><![CDATA[trans_ack_maxcount]]></c>, <c><![CDATA[trans_req_maxcount]]></c>, - <c><![CDATA[trans_req_maxsize]]></c>, <c><![CDATA[trans_ack_maxcount]]></c> and - <c><![CDATA[trans_timer]]></c>). </p> - <p>See also <seeguide marker="megaco_run#transaction_sender">transaction sender</seeguide> for more info. </p> - <p>An <c><![CDATA[boolean]]></c>, defaults to <c><![CDATA[false]]></c>.</p> - - <marker id="ui_trans_req_maxcount"></marker> - </item> - - <tag><c><![CDATA[trans_req_maxcount]]></c></tag> - <item> - <p>Maximum number of accumulated requests. At most this many - requests will be accumulated by the transaction sender - (if started and configured to accumulate requests). </p> - <p>See also <seeguide marker="megaco_run#transaction_sender">transaction sender</seeguide> for more info.</p> - <p>An <c><![CDATA[integer]]></c>, defaults to 10.</p> - <marker id="ui_trans_req_maxsize"></marker> - </item> - <tag><c><![CDATA[trans_req_maxsize]]></c></tag> - <item> - <p>Maximum size of the accumulated requests. At most this much - requests will be accumulated by the transaction sender - (if started and configured to accumulate requests).</p> - <p>See also <seeguide marker="megaco_run#transaction_sender">transaction sender</seeguide> for more info.</p> - <p>An <c><![CDATA[integer]]></c>, defaults to 2048.</p> - - <marker id="ui_trans_timer"></marker> - </item> - <tag><c><![CDATA[trans_timer]]></c></tag> - <item> - <p>Transaction sender timeout time. Has two functions. First, if - the value is 0, then transactions will not be accumulated - (e.g. the transaction sender process will not be started). - Second, if the value is greater then 0 and <c><![CDATA[auto_ack]]></c> - and <c><![CDATA[trans_ack]]></c> are both true or - if <c><![CDATA[trans_req]]></c> is true, - then transaction sender will be started and transactions - (which is depending on the values of <c><![CDATA[auto_ack]]></c>, - <c><![CDATA[trans_ack]]></c> and <c><![CDATA[trans_req]]></c>) will be accumulated, - for later sending. </p> - <p>See also <seeguide marker="megaco_run#transaction_sender">transaction sender</seeguide> for more info. </p> - <p>An <c><![CDATA[integer]]></c>, defaults to 0.</p> - - <marker id="ui_pending_timer"></marker> - </item> - - <tag><c><![CDATA[pending_timer]]></c></tag> - <item> - <p>Automatically send pending if the timer expires before a - transaction reply has been sent. This timer is also called - provisional response timer. </p> - <p>A Megaco Timer (see explanation above), defaults to 30000.</p> - - <marker id="ui_sent_pending_limit"></marker> - </item> - - <tag><c><![CDATA[sent_pending_limit]]></c></tag> - <item> - <p>Sent pending limit (see the MGOriginatedPendingLimit - and the MGCOriginatedPendingLimit of the megaco root package). - This parameter specifies how many pending messages that can - be sent (for a given received transaction request). - When the limit is exceeded, the transaction is aborted - (see <seeerl marker="megaco_user#request_abort">handle_trans_request_abort</seeerl>) and an error message - is sent to the other side. </p> - <p>Note that this has no effect on the actual sending of - pending transactions. This is either implicit (e.g. when - receiving a re-sent transaction request for a request which - is being processed) or controlled by the pending_timer, - see above. </p> - <p>A positive integer or <c><![CDATA[infinity]]></c>, - defaults to <c><![CDATA[infinity]]></c>.</p> - - <marker id="ui_recv_pending_limit"></marker> - </item> - - <tag><c><![CDATA[recv_pending_limit]]></c></tag> - <item> - <p>Receive pending limit (see the MGOriginatedPendingLimit - and the MGCOriginatedPendingLimit of the megaco root package). - This parameter specifies how many pending messages that can - be received (for a sent transaction request). - When the limit is exceeded, the transaction is considered - lost, and an error returned to the user (through the call-back - function <em>handle_trans_reply</em>). </p> - <p>A positive integer or <c><![CDATA[infinity]]></c>, - defaults to <c><![CDATA[infinity]]></c>. </p> - - <marker id="ui_send_mod"></marker> - </item> - - <tag><c><![CDATA[send_mod]]></c></tag> - <item> - <p>Send callback module which exports send_message/2. The - function SendMod:send_message(SendHandle, Binary) is - invoked when the bytes needs to be transmitted to the - remote user. </p> - <p>An <c><![CDATA[atom]]></c>, defaults to <c><![CDATA[megaco_tcp]]></c>.</p> - - <marker id="ui_encoding_mod"></marker> - </item> - - <tag><c><![CDATA[encoding_mod]]></c></tag> - <item> - <p>Encoding callback module which exports encode_message/2 - and decode_message/2. The function - EncodingMod:encode_message(EncodingConfig, - MegacoMessage) is invoked whenever a 'MegacoMessage' - record needs to be translated into an Erlang binary. The - function EncodingMod:decode_message(EncodingConfig, - Binary) is invoked whenever an Erlang binary needs to be - translated into a 'MegacoMessage' record. </p> - <p>An <c><![CDATA[atom]]></c>, defaults to <c><![CDATA[megaco_pretty_text_encoder]]></c>.</p> - - <marker id="ui_encoding_config"></marker> - </item> - - <tag><c><![CDATA[encoding_config]]></c></tag> - <item> - <p>Encoding module config. </p> - <p>A <c><![CDATA[list]]></c>, defaults to <c><![CDATA[[]]]></c>.</p> - - <marker id="ui_protocol_version"></marker> - </item> - - <tag><c><![CDATA[protocol_version]]></c></tag> - <item> - <p>Actual protocol version. </p> - <p>An <c><![CDATA[integer]]></c>, default is 1.</p> - - <marker id="ui_strict_version"></marker> - </item> - - <tag><c><![CDATA[strict_version]]></c></tag> - <item> - <p>Strict version control, i.e. when a message is received, - verify that the version is that which was negotiated. </p> - <p>An <c><![CDATA[boolean]]></c>, default is true.</p> - - <marker id="ui_reply_data"></marker> - </item> - - <tag><c><![CDATA[reply_data]]></c></tag> - <item> - <p>Default reply data. </p> - <p>Any term, defaults to the atom <c><![CDATA[undefined]]></c>.</p> - - <marker id="ui_user_mod"></marker> - </item> - - <tag><c><![CDATA[user_mod]]></c></tag> - <item> - <p>Name of the user callback module. See the the reference - manual for megaco_user for more info.</p> - - <marker id="ui_user_args"></marker> - </item> - - <tag><c><![CDATA[user_args]]></c></tag> - <item> - <p>List of extra arguments to the user callback - functions. See the the reference manual for megaco_user - for more info.</p> - - <marker id="ui_threaded"></marker> - </item> - - <tag><c><![CDATA[threaded]]></c></tag> - <item> - <p>If a received message contains several transaction requests, - this option indicates whether the requests should be handled - sequentially in the same process (<c><![CDATA[false]]></c>), or if each - request should be handled by its own process (<c><![CDATA[true]]></c> - i.e. a separate process is spawned for each request). </p> - <p>An <c><![CDATA[boolean]]></c>, defaults to <c><![CDATA[false]]></c>. </p> - - <marker id="ui_resend_indication"></marker> - </item> - - <tag><c><![CDATA[resend_indication]]></c></tag> - <item> - <p>This option indicates weather the transport module - should be told if a message send is a resend or not. </p> - <p>If <em>false</em>, megaco messages are sent using the - <seeerl marker="megaco_transport#send_message">send_message</seeerl> - function. </p> - <p>If <em>true</em>, megaco message <em>re-sends</em> are made using the - <seeerl marker="megaco_transport#resend_message">resend_message</seeerl> - function. The initial message send is still done using the - <seeerl marker="megaco_transport#send_message">send_message</seeerl> - function. </p> - <p>The special value <em>flag</em> instead indicates that the - function - <seeerl marker="megaco_transport#send_message">send_message/3</seeerl> - shall be used. </p> - <p>A <c>resend_indication()</c>, - defaults to <c><![CDATA[false]]></c>.</p> - - <marker id="ui_segment_reply_ind"></marker> - </item> - - <tag><c><![CDATA[segment_reply_ind]]></c></tag> - <item> - <p>This option specifies if the user shall be notified of received - segment replies or not. </p> - <p>See - <seeerl marker="megaco_user#segment_reply">handle_segment_reply</seeerl> - callback function for more information. </p> - <p>A <c><![CDATA[boolean]]></c>, - defaults to <c><![CDATA[false]]></c>. </p> - - <marker id="ui_segment_recv_timer"></marker> - </item> - - <tag><c><![CDATA[segment_recv_timer]]></c></tag> - <item> - <p>This timer is started when the segment indicated by the - <c><![CDATA[segmentation complete token]]></c> is received, but all - segments has not yet been received.</p> - <p>When the timer finally expires, a "megaco segments not - received" (459) error message is sent to the other side - and the user is notified with a <c><![CDATA[segment timeout]]></c> <c><![CDATA[UserReply]]></c> in either the - <seeerl marker="megaco_user#trans_reply">handle_trans_reply</seeerl> callback function or - the return value of the - <seeerl marker="megaco#call">call</seeerl> function. </p> - <p>A Megaco Timer (see explanation above), - defaults to <c><![CDATA[10000]]></c>. </p> - - <marker id="ui_segment_send"></marker> - </item> + <marker id="user_info_21"></marker> + </desc> + </func> - <tag><c><![CDATA[segment_send]]></c></tag> - <item> - <p>Shall outgoing messages be segmented or not: </p> - <taglist> - <tag><c><![CDATA[none]]></c></tag> - <item> - <p>Do not segment outgoing reply messages. This is useful when - either it is known that messages are never to large or - that the transport protocol can handle such things - on its own (e.g. TCP or SCTP).</p> - </item> - <tag><c><![CDATA[integer() > 0]]></c></tag> - <item> - <p>Outgoing reply messages will be segmented as needed - (see <c><![CDATA[max_pdu_size]]></c> below). This value, K, indicate - the outstanding window, i.e. how many segments can be - outstanding (not acknowledged) at any given time. </p> - </item> - <tag><c><![CDATA[infinity]]></c></tag> - <item> - <p>Outgoing reply messages will be segmented as needed - (see <c><![CDATA[max_pdu_size]]></c> below). Segment messages - are sent all at once (i.e. no acknowledgement awaited - before sending the next segment). </p> - </item> - </taglist> - <p>Defaults to <c><![CDATA[none]]></c>. </p> + <func> + <name name="user_info" arity="2" clause_i="1" since=""/> + <fsummary>Lookup user information</fsummary> + <desc> + <p>Lookup user information about currently active requests. </p> - <marker id="ui_max_pdu_size"></marker> - </item> + <marker id="user_info_22"></marker> + </desc> + </func> - <tag><c><![CDATA[max_pdu_size]]></c></tag> - <item> - <p>Max message size. If the encoded message (PDU) exceeds - this size, the message should be segmented, and then - encoded. </p> - <p>A positive integer or <c><![CDATA[infinity]]></c>, - defaults to <c><![CDATA[infinity]]></c>. </p> - </item> - </taglist> + <func> + <name name="user_info" arity="2" clause_i="2" since=""/> + <fsummary>Lookup user information</fsummary> + <desc> + <p>Lookup user information about currently active replies. </p> <marker id="update_user_info"></marker> </desc> diff --git a/lib/megaco/src/app/megaco.erl b/lib/megaco/src/app/megaco.erl index 39440f2304..24d4cea76a 100644 --- a/lib/megaco/src/app/megaco.erl +++ b/lib/megaco/src/app/megaco.erl @@ -307,10 +307,33 @@ stop_user(UserMid) -> %% Lookup user information %%----------------------------------------------------------------- +-spec user_info(UserMid) -> [{Item, Value}] when + UserMid :: mid(), + Item :: requests | replies | user_info_item(), + Value :: term(). + user_info(UserMid) -> [{requests, user_info(UserMid, requests)}, {replies, user_info(UserMid, replies)} | user_info(UserMid, all)]. +-spec user_info(UserMid, requests) -> [{Conn, [TransId]}] when + UserMid :: mid(), + Conn :: conn_handle(), + TransId :: transaction_id(); + + (UserMid, replies) -> + [{Conn, [{TransId, ReplyState, Handler}]}] when + UserMid :: mid(), + Conn :: conn_handle(), + TransId :: transaction_id(), + ReplyState :: prepare | eval_request | waiting_for_ack | aborted, + Handler :: undefined | pid(); + + (UserMid, Item) -> Value when + UserMid :: mid(), + Item :: user_info_item(), + Value :: term(). + user_info(UserMid, requests) -> megaco_messenger:which_requests(UserMid); user_info(UserMid, replies) -> @@ -347,8 +370,10 @@ conn_info(ConnHandle) -> {replies, conn_info(ConnHandle, replies)} | conn_info(ConnHandle, all)]. --spec conn_info(ConnHandle, all) -> [{conn_info_item(), term()}] when - ConnHandle :: conn_handle(); +-spec conn_info(ConnHandle, all) -> [{Item, Value}] when + ConnHandle :: conn_handle(), + Item :: conn_info_item(), + Value :: term(); (ConnHandle, requests) -> [TransId] when ConnHandle :: conn_handle(), -- 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
