Network Object Reference
From Zenitel Wiki
(Redirected from ECL ANNOUNCEMENT)In the AlphaNet Data Protocol all exchange resources can be referenced either by directory numbers, or “physical numbers”. This is a challenge for the data protocol, as directory numbers can vary in size, and some resources have physical addresses with multiple parts. The NET_OBJ_REF is a “variant record” which has a header with byte count plus a type field. The rest of the information is then according to the type field and length.
The total length can vary from 1 to 16 bytes.
NOTE: AlphaCom 08.00 have a fixed size internally of 6 bytes for NET_OBJ_REF fields.
Contents
NET_OBJ_REF format
- <header> <contents….>
Where:
- <header> UINT1 defines both the length and the format:
- <length> 4 bits. The length of the representation not including the first byte itself.
- <format> 4 bits. The format of the representation. See the table below.
- <contents> See the table below.
Format number |
Magic char Prefix |
Format name Object layout / Description |
---|---|---|
Format 0 | G | NRF_DIGIT_STRING / NRF_GLOBAL_DIRNO
Represent digits to be dialed. The interpretation is up to the receiving exchange, and the string may be an incomplete dir.no, a complete dir.no, or a dir.no followed by additional parameters. |
Format 1 | --- | (reserved) |
Format 2 | L | NRF_LOCAL_DIRNO Represents a complete directory number in an exchange. <header> <node> <digit string….> <node>: UINT1. The node number specifies in which node the directory number is valid. |
Format 3 | N | NRF_LOCAL_ENTITY Refer to an intercom object with the internal binary identification. <header> <node> <entity class> <internal id> [<entity subclass>] <node> UINT1 <entity class> UINT1 What class of intercom object it is referred to. See table below. <internal id> 1-13 bytes binary. (individ) number. Only 2 byte (UINT2/SINT2) values are currently supported. <entity sub-class> UINT1 (Optional) Omitted unless use of the subclass information is described explicitly for the given message. Provides a more detailed SubClassing within the given Entity Class when needed. - Which of the different subclassing schemes is used for a given message parameter is mentioned in the message parameter description if any subclassing is used at all. - The value 0 is reserved for internal use and should not be used in a data protocol message. The literals below refer to the AlphaCom/7.2x implementation. Not all classes are useful in the currently defined messages. The valid ranges may differ between exchange types and even SW versions. Example: Hex { 43 05 06 00 01 } means node 5, audio program 1 NULL: Hex { 43 00 00 00 00 } |
Format 4 | P | NRF_PHYS_ADDR
Refer to an intercom object by physical hardware address. The address is unique within a network of interconnected exchanges. |
5..14 | (reserved) | |
Format 15 | I | INVALID_NRF This signifies an invalid value, used internally in a system. Not allowed in a DP message. <header> The length field is allowed to be anything but should normally be 0 (1 byte total). Example: { 0x0F }. NULLvalue: the proper value in a valid format should be used instead. |
NET_OBJ_REF: Entity Classes
Used when referring to an intercom object with internal binary (“physical”) identification.
Type | Name | Value (internal id) | Null | Comments | Magic character |
---|---|---|---|---|---|
0 | INVALID_ECL | --- | |||
1 | ECL_ABSENT | 1-30 | 0 | A | |
2 | ECL_ANNOUNCEMENT | 1-9 | 0 | ! | |
3 | ECL_FEATURE | 1-82 | 255 | O | |
4 | ECL_MAIL | 1-32 Mail message number |
0 | Call Request may be responsed by ECL_MAIL_PRIO | M |
5 | ECL_ST_GROUP | 1-50 | 0 | G | |
6 | ECL_PROGRAM | 1-38 | 0 | P | |
7 | ECL_PROG_CONF | 1-50 | 0 | C | |
8 | ECL_STATION | 1-552 | 0 | (default) | |
9 | ECL_USER | 1-600 | 0 | U | |
10 | ECL_MAIL_PRIO | 0-511 | Values 0-255 represents normal call requests. Values > 256 represents alternative text call requests, with priority = value - 256. |
+ | |
11 | ECL_FEAT_CONN | 1-82 | 255 | I | |
12 | ECL_NODE | 0/1 254 | 255 | N | |
13 | ECL_GLOB_NUMBER | % | |||
14 | ECL_GLOB_GROUP | 1-50 | 0 | & | |
15 | ECL_O_DUPL_CONF | 1-20 | 0 | F | |
16 | ECL_BOARD | 1-255 1-26(63) |
0 64 |
Value is UINT2: MSB is device addr LSB is board addr. | B |
17 | ECL_DEVICE | 1-255 | 0 | D | |
18 | ECL_AUDIO_RING | 1-24 | 0 | R | |
19 | ECL_AUDIO_LINK | 1-138 | 0 | --- | |
20 | ECL_DP_LINK | 0-7 | 255 | --- | |
21-255 | --reserved for future use-- | --- |
NET_OBJ_REF: Entity Subclasses
Used when very specific information is given, e.g. during error reporting. Subclasses are defined so that they can be used also for future exchange types working in AlphaNet.
Scheme | Entity Subclass | Description | ||
---|---|---|---|---|
generic | NULL 1 - 255 0 |
INVALID_ESC ---reserved for future use--- ---reserved for internal use--- |
Unspecified SubClass / Not Applicable ---illegal in NET_OBJ_REF value--- | |
interface types |
NULL 1 2 3 |
ESC_ANY_IF ESC_TL_ABCD_IF ESC_ANALOG_PHONE_IF ESC_AUDIO_0DB_IF |
Unspecified Interface Type TouchLine ABCD Station Interface Interface to Plain Old Analog Telephone 4(2) wire 0dB Analog Audio Interface |
(e.g. ASLT) (e.g. ATLB) (e.g. AGA) |
- Different Schemes should use nonoverlapping value sets as long as there are enough available values --- Except for the NULL value that is shared by all schemes.
- NULL is represented by missing Entity SubClass field in NET_OBJ_REF value. The value 0 is reserved for representing this value in separate subclass variables internally in software.
Additional notes
- NET_OBJ_REF parameters: Where an entity class is given (Example: {ECL_ABSENT}), the parameter must be either a LOCAL_ENTITY format reference of the correct class or a directory number that maps to an entity of the correct class, or a Null value, if allowed.
- Except: ECL_USER and ECL_STATION can be used interchangeably, and will be converted to the other type when needed. As a side effect of this, the returned directory number reference for a ECL_STATION type object may be different from the one in the command message, or even invalid, if the directory number or user reference in the command message is not the one of the default user of the station.
- NET_OBJ_REF parameters are by default output in the LOCAL_DIRNO format by AlphaCom and TouchLine. Exceptions are noted in each case.
- For the reason above and other reasons, NET_OBJ_REF parameters in command messages can not be relied upon to match the corresponding NET_OBJ_REF parameters in response messages. If one need to sort responses of the same message type from each other, the message reference field in the application header should be used.
Notes for implementation
On the use of LOCAL_ENTITY
In the data protocol document each message parameter is specified like NET_OBJ_REF {ECL_STATION, ECL_GROUP}. This parameter then accepts a NRF_LOCAL_ENTITY with the listed entity_classes. In addition, its always allowed to use a NRF_LOCAL_DIRNO instead. The directory number must have a suitable feature number in the exchange which accesses the correct physical resource. In the example above, either feature 9 (Call a user), or feature 39 (Group Call).
Strategy for use of formats - automatic translations
The AlphaCom has the following general rule for formats:
- Data from/to external devices should use directory number references
- Data to/from other intercom devices (AlphaNet nodes) should use entity (physical number) references
The ideas is that e.g. a PC application should use the format a human uses on his station keyboard/display, while physical addresses are better suited for machine-machine communication. The AlphaCom translates incoming parameters in _LOCAL_DIRNO format to _LOCAL_ENTITY format, handles the command, and translates back to _LOCAL_DIRNO again in response messages.
The AlphaCom is not able to remember the format of the incoming message, so even if you use _LOCAL_ENTITY in your commands, _LOCAL_DIRNO is returned! This may create a problem in recognising the responses, but for that purpose you can use the application layer’s “reference” field.
Note that if a station has no directory number, the NET_OBJ_REF will contain a _LOCAL_ENTITY. Your application should accept this format and handle it gracefully. Stations without directory number can be used to obtain certain effects like “technical” audio ports. You should also be aware that some broadcast messages will identify AlphaNet audio AGA ports rather than the remote dir.nos, and in these cases you may also se unexpected _LOCAL_ENTITY formats.
On the use of NULL
Due to the possibility for several formats, your application must be prepared to accept all valid formats!