Network Object Reference

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.

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.   <header> <digit string….>     <digit string>: This format has 0 to 15 bytes of BCD­coded digits. That means that digit strings up to 30 digits may be represented in this format (Max 10 in AMC 08.00). - Unused nibbles must be set to 15 (0xF / INVALID_DIGIT). - The extended digits 10-14 (0xA-0xE) are allowed in the format, but not yet supported by AlphaCom. TouchLine MPC may support them to some extent. - Only 0 or 1 padding nibble will be needed for any digit string, but extra padding bytes (0xFF) may be added if desired to simplify formatting. The string may either be a directory number as dialed from a station, possibly including an area code for accessing another node, or any other kind of digit string representing phone numbers, dates, etc.   Example: Hex { 20 10 7F } is digit string “107”. NULL value : Hex { 00 } A zero­length string.
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. - Value 0 (LOCAL_NODE) can be used when one wants to specify the local node, but does not know its node number. - The value 255 can be used either as an NULL/INVALID value or to signify broadcast. <digit string>: This format has 0 to 14 bytes of BCD­coded digits. See format 0 for details.   Example: Hex { 32 02 10 2F } is node 2, directory number ``102’’ NULL value: Hex { 12 00 }.
Format 3	N	NRF_LOCAL_ENTITY Refer to an intercom object with the internal binary identification.   <header> <node> <entity class> <internal id> [<entity sub­class>]   <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 Sub­Classing 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.   <header> <node> <device> <board> <interface number> <interface type>   <node> UINT1 The node number specifies in which node the description is valid. <device> UINT1 Device Number. <board> UINT1 Board Number/Position. Only position 1...26 are supported by HW. <interface number> UINT1 Interface/Entity Individ Number. Which individ within the given board and type. Individs are by default numbered from 1. Example: Interface 1--16 on an AGA board, 1 – 32 on AE1, 1 – 6 on ASLT. <interface type> UINT1 Interface/Address Type. Used for interface/address types not default or implicitly defined by context. - This field is originally intended for use when there are different types of interfaces/resources on the same board type, like for example a(n imaginary) new board type with both subscriber line interfaces and program feeds on it. - Type value 0 is reserved for internal use and should not be used externally. Type values 224­255 has been reserved for full Unit Addresses in case this low­level internal addressing will be needed on ACDP some time in the future.   How many of these fields (from the start) one includes defines the class of physical address: 1 field: Physical Exchange (Node) Address 2 fields: Physical Device Address 3 fields: Physical Board Address. 4 fields: Physical Resource Address (with implicit resource address type). 5 fields: Physical Resource Address with explicit resource address type. No application identified yet. 4 fields is preferred over 5 wherever both are possible. 4 fields will therefore also be used for one of the resource address types (the default / most­used one) in contexts where more than one type can be referred.   Example: Hex { 44 05 41 09 02 } means node 5, exchange device, board 9, ASLT port 2   NULL: Hex { 14 00 }
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 }. NULL­value: 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 non­overlapping 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!