megaco_binary_name_resolver_v2.erl

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: Handle meta data about packages
%%----------------------------------------------------------------------

-module(megaco_binary_name_resolver_v2).

-include_lib("megaco/src/engine/megaco_message_internal.hrl").
-include_lib("megaco/src/app/megaco_internal.hrl").

-define(LOWER(Char),
	if
	    Char >= $A, Char =< $Z ->
		Char - ($A - $a);
	    true ->
		Char
	end).

-export([packages/0,
	 capabilities/0,
	 capabilities/1,
         decode_name/3,
	 encode_name/3
        ]).

encode_name(Config, term_id, TermId) ->
    case megaco:encode_binary_term_id(Config, TermId) of
	{ok, TermId2} ->
	    TermId2;
	{error, _Reason} ->
	    exit({bad_term_id, TermId})
    end;	
encode_name(_Config, Scope, Item) ->
    ?d("encode_name(~p) -> entry with"
       "~n   Item: ~p", [Scope, Item]),
    encode(Scope, Item).

decode_name(Config, term_id, TermId) ->
    case megaco:decode_binary_term_id(Config, TermId) of
	{ok, TermId2} ->
	    TermId2;
	{error, _Reason} ->
	    exit({bad_term_id, TermId})
    end;
decode_name(_Config, Scope, Item) ->
    ?d("decode_name(~p) -> entry with"
       "~n   Item: ~p", [Scope, Item]),
    decode(Scope, Item).

%%----------------------------------------------------------------------
%% 12.1.1   Package
%% 
%%    Overall description of the package, specifying:
%% 
%%       Package Name: only descriptive
%% 
%%       PackageID: is an identifier
%% 
%%       Description:
%% 
%%       Version:
%% 
%%    A new version of a package can only add additional Properties,
%%    Events, Signals, Statistics and new possible values for an existing
%%    parameter described in the original package. No deletions or
%%    modifications shall be allowed. A version is an integer in the range
%%    from 1 to 99.
%% 
%%       Designed to be extended only (Optional): Yes
%% 
%%    This indicates that the package has been expressly designed to be
%%    extended by others, not to be directly referenced. For example, the
%%    package may not have any function on its own or be nonsensical on its
%%    own. The MG SHOULD NOT publish this PackageID when reporting
%%    packages.
%% 
%%       Extends (Optional): existing package Descriptor
%% 
%%    A package may extend an existing package. The version of the original
%%    package must be specified. When a package extends another package it
%%    shall only add additional Properties, Events, Signals, Statistics and
%%    new possible values for an existing parameter described in the
%%    original package. An extended package shall not redefine or overload
%%    an identifier defined in the original package and packages it may
%%    have extended (multiple levels of extension). Hence, if package B
%%    version 1 extends package A version 1, version 2 of B will not be
%%    able to extend the A version 2 if A version 2 defines a name already
%%    in B version 1.
%% 
%% 
%% 12.1.2   Properties
%% 
%%    Properties defined by the package, specifying:
%% 
%%       Property Name: only descriptive
%% 
%%       PropertyID: is an identifier
%% 
%%       Description:
%% 
%%       Type: One of:
%% 
%%          Boolean
%% 
%%          String: UTF-8 string
%% 
%%          Octet String: A number of octets.  See Annex A and Annex B.3
%%          for encoding
%% 
%%          Integer: 4 byte signed integer
%% 
%%          Double: 8 byte signed integer
%% 
%%          Character: unicode UTF-8 encoding of a single letter. Could be
%%          more than one octet.
%% 
%%          Enumeration: one of a list of possible unique values (see 12.3)
%% 
%%          Sub-list: a list of several values from a list. The type of
%%          sub-list SHALL also be specified.  The type shall be chosen
%%          from the types specified in this section (with the exception of
%%          sub-list). For example, Type: sub-list of enumeration.  The
%%          encoding of sub-lists is specified in Annexes A and B.3.
%% 
%%       Possible values:
%% 
%%    A package MUST specify either a specific set of values or a
%%    description of how values are determined.  A package MUST also
%%    specify a default value or the default behaviour when the value is
%%    omitted from its descriptor.  For example, a package may specify that
%%    procedures related to the property are suspended when it value is
%%    omitted.  A default value (but not procedures) may be specified as
%%    provisionable.
%% 
%%       Defined in:
%% 
%%    Which H.248.1 descriptor the property is defined in. LocalControl is
%%    for stream dependent properties. TerminationState is for stream
%%    independent properties. These are expected to be the most common
%%    cases, but it is possible for properties to be defined in other
%%    descriptors.
%% 
%%       Characteristics: Read/Write or both, and (optionally), global:
%% 
%%    Indicates whether a property is read-only, or read-write, and if it
%%    is global. If Global is omitted, the property is not global. If a
%%    property is declared as global, the value of the property is shared
%%    by all Terminations realizing the package.
%% 
%% 
%% 12.1.3   Events
%% 
%%    Events defined by the package, specifying:
%% 
%%       Event name: only descriptive
%% 
%%       EventID: is an identifier
%% 
%%       Description:
%% 
%%       EventsDescriptor Parameters:
%% 
%%    Parameters used by the MGC to configure the event, and found in the
%%    EventsDescriptor. See 12.2.
%% 
%%       ObservedEventsDescriptor Parameters:
%% 
%%    Parameters returned to the MGC in Notify requests and in replies to
%%    command requests from the MGC that audit ObservedEventsDescriptor,
%%    and found in the ObservedEventsDescriptor. See 12.2.
%% 
%% 
%% 12.1.4   Signals
%% 
%%    Signals defined by the package, specifying:
%% 
%%       Signal Name: only descriptive
%% 
%%       SignalID: is an identifier. SignalID is used in a
%%       SignalsDescriptor
%% 
%%       Description
%% 
%%       SignalType: one of:
%% 
%%             OO (On/Off)
%% 
%%             TO (TimeOut)
%% 
%%             BR (Brief)
%% 
%%    NOTE - SignalType may be defined such that it is dependent on the
%%    value of one or more parameters. The package MUST specify a default
%%    signal type.  If the default type is TO, the package MUST specify a
%%    default duration which may be provisioned.  A default duration is
%%    meaningless for BR.
%% 
%%       Duration: in hundredths of seconds
%% 
%%       Additional Parameters: see 12.2
%% 
%% 
%% 12.1.5   Statistics
%% 
%%    Statistics defined by the package, specifying:
%% 
%%       Statistic name: only descriptive
%% 
%%       StatisticID: is an identifier
%% 
%%    StatisticID is used in a StatisticsDescriptor
%% 
%%       Description:
%% 
%%       Type: One of:
%%           Boolean
%%           String: UTF-8 string
%%           Octet String: A number of octets. See Annex A and B.3 for encoding
%%           Integer: 4 byte signed integer
%%           Double: 8 byte signed integer
%%           Character: Unicode UTF-8 encoding of a single letter. 
%%                             Could be more than one octet.
%%           Enumeration: One of a list of possible unique values (see 12.3)
%%           Sub-list: A list of several values from a list. 
%%                     The type of sub-list SHALL also be specified. 
%%                     The type shall be chosen from the types specified
%%                     in this clause (with the exception of sub-list). 
%%                     For example, Type: sub-list of enumeration. 
%%                     The encoding of sub-lists is specified in 
%%                     Annex A and B.3.
%%       Possible Values:
%%           A package must indicate the unit of measure, e.g., 
%%           milliseconds, packets, either here or along with the type 
%%           above, as well as indicating any restriction on the range.
%% 
%% 
%% 12.1.6   Procedures
%% 
%%    Additional guidance on the use of the package.
%% 
%% 
%% 12.2  Guidelines to defining Parameters to Events and Signals
%% 
%%       Parameter Name: only descriptive
%% 
%%       ParameterID: is an identifier. The textual ParameterID of
%%       parameters to Events and Signals shall not start with "EPA" and
%%       "SPA", respectively. The textual ParameterID shall also not be
%%       "ST", "Stream", "SY", "SignalType", "DR", "Duration", "NC",
%%       "NotifyCompletion", "KA", "Keepactive", "EB", "Embed", "DM" or
%%       "DigitMap".
%% 
%%       Type: One of:
%% 
%%          Boolean
%% 
%%          String: UTF-8 octet string
%% 
%%          Octet String: A number of octets.  See Annex A and Annex B.3
%%          for encoding
%% 
%%          Integer: 4-octet signed integer
%% 
%%          Double: 8-octet signed integer
%% 
%%          Character: unicode UTF-8 encoding of a single letter. Could be
%%          more than one octet.
%% 
%%          Enumeration: one of a list of possible unique values (see 12.3)
%% 
%%          Sub-list: a list of several values from a list (not supported
%%          for statistics). The type of sub-list SHALL also be specified.
%%          The type shall be chosen from the types specified in this
%%          section (with the exception of sub-list). For example, Type:
%%          sub-list of enumeration.  The encoding of sub-lists is
%%          specified in Annexes A and B.3.
%% 
%%       Possible values:
%% 
%%    A package MUST specify either a specific set of values or a
%%    description of how values are determined.  A package MUST also
%%    specify a default value or the default behavior when the value is
%%    omitted from its descriptor.  For example, a package may specify that
%%    procedures related to the parameter are suspended when it value is
%%    omitted.  A default value (but not procedures) may be specified as
%%    provisionable.
%% 
%%       Description:
%% 
%% 
%% 12.3  Lists
%% 
%%    Possible values for parameters include enumerations. Enumerations may
%%    be defined in a list. It is recommended that the list be IANA
%%    registered so that packages that extend the list can be defined
%%    without concern for conflicting names.
%% 
%% 
%% 12.4  Identifiers
%% 
%%    Identifiers in text encoding shall be strings of up to 64 characters,
%%    containing no spaces, starting with an alphabetic character and
%%    consisting of alphanumeric characters and/or digits, and possibly
%%    including the special character underscore ("_").
%% 
%%    Identifiers in binary encoding are 2 octets long.
%% 
%%    Both text and binary values shall be specified for each identifier,
%%    including identifiers used as values in enumerated types.
%% 
%% 
%% 12.5  Package registration
%% 
%%    A package can be registered with IANA for interoperability reasons.
%%    See clause 14 for IANA considerations.
%% 
%%----------------------------------------------------------------------

capabilities() ->
    [{P, capabilities(P)} || P <- packages()].

%% -record(property, {name, type, values, defined_in, characteristics}).

%%----------------------------------------------------------------------
%% List all known packages
%% 'native' and 'all' are not real packages
%%----------------------------------------------------------------------

packages() ->
    [
     "g",        % Generic
     "root",	 % Base Root Package
     "tonegen",	 % Tone Generator Package
     "tonedet",	 % Tone Detection Package
     "dg",	 % Basic DTMF Generator Package
     "dd",	 % DTMF detection Package
     "cg",	 % Call Progress Tones Generator Package
     "cd",	 % Call Progress Tones Detection Package
     "al",	 % Analog Line Supervision Package
     "ct",	 % Basic Continuity Package
     "nt",	 % Network Package
     "rtp",	 % RTP Package
     "swb",	 % SwitchBoard Package
     "tdmc",     % TDM Circuit Package
     ""          % Native pseudo package
    ].

%%----------------------------------------------------------------------
%% List all matching capabilities
%%----------------------------------------------------------------------

capabilities(Package) ->
    case Package of
        "g"       -> capabilities_g();
        "root"    -> capabilities_root();
        "tonegen" -> capabilities_tonegen();
        "tonedet" -> capabilities_tonedet();
        "dg"      -> capabilities_dg();
        "dd"      -> capabilities_dd();
        "cg"      -> capabilities_cg();
        "cd"      -> capabilities_cd();
        "al"      -> capabilities_al();
        "ct"      -> capabilities_ct();
        "nt"      -> capabilities_nt();
        "rtp"     -> capabilities_rtp();
	"swb"     -> capabilities_swb();
        "tdmc"    -> capabilities_tdmc();
        ""        -> capabilities_native()
    end.

%%----------------------------------------------------------------------
%% Decode package name to internal form
%% Scope  ::= property | event | signal | statistics
%%----------------------------------------------------------------------

decode(mid, Package) ->
    decode_mid(Package);
decode(package, Package) ->
    decode_package(Package);
decode(profile, Package) ->
    decode_profile(Package);
decode(dialplan, Dialplan) ->
    decode_dialplan(Dialplan);
decode(Scope, [A, B | Item]) when atom(Scope) ->
    ?d("decode(~p) -> entry with"
       "~n   A:    ~p"
       "~n   B:    ~p"
       "~n   Item: ~p", [Scope, A, B, Item]),
    case decode_package([A, B]) of
	"" ->
 	    ?d("decode -> \"no\" package",[]),
	    decode_item(Scope, [A, B], Item);
	Package ->
 	    ?d("decode -> Package: ~p", [Package]),
	    Package ++ "/" ++ decode_item(Scope, [A, B], Item)
    end;
decode({Scope, [A, B | Item]}, SubItem) when atom(Scope) ->
    ?d("decode(~p) -> entry with"
       "~n   A:       ~p"
       "~n   B:       ~p"
       "~n   Item:    ~p"
       "~n   SubItem: ~p", [Scope, A, B, Item, SubItem]),
    decode_item({Scope, Item}, [A, B], SubItem).