megaco.hrl

OTP是开放电信平台的简称

%% ``The contents of this file are subject to the Erlang Public License,
%% Version 1.1, (the "License"); you may not use this file except in
%% compliance with the License. You should have received a copy of the
%% Erlang Public License along with this software. If not, it can be
%% retrieved via the world wide web at http://www.erlang.org/.
%% 
%% Software distributed under the License is distributed on an "AS IS"
%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
%% the License for the specific language governing rights and limitations
%% under the License.
%% 
%% The Initial Developer of the Original Code is Ericsson Utvecklings AB.
%% Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
%% AB. All Rights Reserved.''
%% 
%%     $Id$
%%
%%----------------------------------------------------------------------
%% Purpose: Define common data structures and error codes
%%----------------------------------------------------------------------

%%----------------------------------------------------------------------
%% Receive handle
%%
%% The receive handle contains enough information in order
%% to be able to decode a message and send a reply to the
%% originator.
%%----------------------------------------------------------------------

-record(megaco_receive_handle,
        {
          local_mid,
          encoding_mod,
          encoding_config,
          send_mod,
	  protocol_version = dynamic % dynamic | integer()
         }).

%%----------------------------------------------------------------------
%% Connection handle
%%
%% The connecion handle provides a locally unique identity of a
%% connection. It is generated when a connection is established.
%%----------------------------------------------------------------------

-record(megaco_conn_handle,
        {
          local_mid,
          remote_mid
         }).

%%----------------------------------------------------------------------
%% Incremental timer
%%
%% The timer sleeps in WaitFor milli seconds and when it
%% times out, a new time out value is computed:
%%
%%   WaitFor2 = WaitFor * Factor + Incr
%%   
%% And the timer starts all over again with the new WaitFor value.
%% The procedure is repeated at at most MaxRetries.
%% 
%% There is a special case for this timer. When the max_retries has
%% the value infinity_restartable it means that the timer is
%% restartable as long as some external event occurs (e.g. receipt of
%% a pending message for instance). But the timer will never be
%% restarted "by itself". I.e. when the timer expires (whatever the
%% timeout time), so does the timer. Whever the timer is restarted,
%% the timeout time will be calculated in the usual way!
%% 
%%----------------------------------------------------------------------

-record(megaco_incr_timer,
        {wait_for    = timer:seconds(7),% Initial timeout (milli seconds)
         factor      = 2,               % Factor to multiply with at timeout
         incr        = 0,               % Milli seconds to add at timeout
         max_retries = infinity}).      % infinity | infinity_restartable | Integer

%%----------------------------------------------------------------------
%% The internal representation of a termination id
%%----------------------------------------------------------------------
%%
%% id()                 -> [level()]
%% level()              -> [char()]
%% char()               -> wildcard() | $0 | $1 | text_only_char()
%% text_only_char()     -> $2..$9 | $a..$z | $_ | $. | $@
%% wildcard()           -> all() | choose()
%% all()                -> $*
%% choose()             -> $$
%% contains_wildcards() -> true | false
%%
%% The id field contains all info about the termination id, while the
%% presense of the contains_wildcards field is just as a matter of
%% convenience in order to make it simple to determine whether a
%% simple id lookup will suffice or if some more complicated matching
%% algorithm is needed.
%% 
%% Some text encoding examples:
%%
%%   "ROOT"     -> {megaco_term_id, false, [[$r,$o,$o,$t]]}
%%   "*"        -> {megaco_term_id, true,  [[$*]]}
%%   "$"        -> {megaco_term_id, true,  [[$$]]}
%%   "R1/101/1" -> {megaco_term_id, false, [[$r, $1], [$1, $0,  $1], [$1]]}
%%   "R1/1*1/*" -> {megaco_term_id, true,  [[$r, $1], [$1, all, $1]], [$*]}
%%   "R1/1*"    -> {megaco_term_id, true,  [[$r, $1], [$1, $*]]}
%%   "R1/1*/"   -> {megaco_term_id, true,  [[$r, $1], [$1, $*], []]}
%%   
%% Given the terminations "R1/10", "R1/101/0" and "R1/101/1" the above 
%% termination identifiers would be resolved to the following ones:
%% 
%%   "ROOT"     -> "ROOT"
%%   "*"        -> "R1/10"    and "R1/101/0" and "R1/101/1"
%%   "$"        -> "R1/10"    or  "R1/101/0" or  "R1/101/1"
%%   "R1/101/1" -> "R1/101/1"
%%   "R1/1*1/*" -> "R1/101/1" and "R1/101/0"
%%   "R1/1*"    -> "R1/10"    and "R1/101/0" and "R1/101/1"
%%   "R1/1*/"   -> "R1/10"
%%
%% In the binary encoding it is possible to express whether the last
%% wildcard pertains to a certain level, in the hierarchical naming
%% scheme (in the internal form this is expressed as an empty list as
%% last level, see the internal form for "R1/1*/" above) or if the
%% match also should include all lower levels recursively (see the
%% internal form for "R1/1*" above).
%%
%% Observe that a termination id with a trailing slash (such as
%% "R1/1*/") violates the text encoding protocol. But we allow it
%% anyway since the corresponding internal form is needed for the
%% binary encoding. It is also nice to be able to pretty print any
%% binary termination id as text.
%%
%% A fully specified binary termination id:
%%
%%   #'TerminationID'{wildcard = [],
%%                   id        = [2#00000001, 02#0011110, 2#00000000]}
%%
%% is internally represented as:
%%   
%%   #megaco_term_id{contains_wildcards = false,
%%                   id                 = [[$0, $0, $0, $1, $1, $1, $1, $0],
%%                                         [$0, $1, $0, $1, $0, $1, $0, $1],
%%                                         [$0, $0, $0, $0, $0, $0, $0, $0]]}
%%                            
%% Addressing all names with prefix 00000001 00011110 is done as follows:
%% 
%%   #'TerminationID'{wildcard = [2#10000111],
%%                   id        = [2#00000001, 2#00011110, 2#00000000]}
%%   
%% is internally represented as:
%%   
%%   #megaco_term_id{contains_wildcards = true,
%%                   id                 = [[$0, $0, $0, $0, $0, $0, $0, $1],
%%                                         [$0, $0, $0, $1, $1, $1, $1, $0],
%%                                         [?megaco_all]}
%% 
%% Indicating to the receiver that is must choose a name with 00011110 as
%% the second octet is done as follows:
%% 
%%   #'TerminationID'{wildcard = [2#00010111, 2#00000111],
%%                   id        = [2#00000000, 2#00011110, 2#00000000]}
%%   
%% is internally represented as:
%%   
%%   #megaco_term_id{contains_wildcards = true,
%%                   id                 = [[?megaco_choose],
%%                                         [$0, $0, $0, $1, $1, $1, $1, $0],
%%                                         [?megaco_choose]]}