megaco_binary_name_resolver_v1.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_v1).

-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):
%% 
%%          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 its 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:
%% 
%%       Units: unit of measure, e.g., milliseconds, packets
%% 
%% 
%% 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 13 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]),