M3uaRetrieveMessage

Checks for and retrieves an incoming message from the M3UA layer.

Prototype

DWORD NMSAPI M3uaRetrieveMessage ( CTAHD ctahd, void *pMsgInd, short *Length)

Argument

Description

ctahd

Natural Access handle.

pMsgInd

Pointer to the buffer where the received message is returned. The size of the buffer must be large enough to contain a data indication. See the Details section for more information about data indications.

Length

Pointer to the buffer where the length of the incoming message is returned.


Return values

Return value

Description

M3UA_SUCCESS

 

M3UA_INVBOARD

Invalid board number.

M3UA_NOT_BOUND

ctaOpenServices not previously called.

M3UA_NO_MSG

No message currently waiting.


Details

To process incoming messages, the application can perform one of the following tasks:

Applications can receive the following types of messages:

Data indications

An application receives a DATA_IND structure when a remote signaling point sends data matching the application's service information octet:

typedef struct data_ind_s 
{
  U8   code;           /* M3UA_DATA_IND (0x1A)              */
  U8   spare1;         /* Alignment                         */
  U16  sapId;          /* Service user Id from Open Services*/
  U32  opc;            /* Originating Point Code            */
  U32  dpc;            /* Destination Point Code            */
  U8   srvInfo;        /* Service information octet         */
  U8   lnkSel;         /* Link selector field               */
  U16  spare2;         /* Alignment                         */
  U8   data[MAXDATA]   /* Received data packet              */
} DATA_IND;

DATA_IND contains the following fields:

Field

Description

code

Always set to M3UA_DATA_IND, for data indications.

sapID

Service user identifier passed as suId in ctaOpenServices.

opc

Point code of the remote node that sent this data. Valid values are 0 through 0xFFFFFF.

dpc

Destination point code from the routing label of the incoming message. Valid values are 0 through 0xFFFFFF.

srvInfo

Service information octet from the incoming message specifying the upper task protocol and the network indicator.

lnkSel

Link selector field from the incoming message. Valid values are:

0 through 15 (ITU-T)

0 through 31 (ANSI)

0 through 255 (TUP or 8-bit ANSI)

data [MAXDATA]

Array of size MAXDATA where received data is stored.


Status indications

An application receives a STAT_IND structure when an important status change occurs. Status changes may be generated by the local M3UA layer or received from a remote MTP3 layer via a signaling gateway (SG). For more information, see Status indications.

typedef struct stat_ind_s 
{
  U8   code;      /* M3UA_STAT_IND (0x7A)                 */
  U8   spare1;    /* Alignment                            */
  U16  sapId;     /* Service user Id from Open Services   */
  U32  pc;        /* Point Code related to the status ind */
  U32  opc;       /* Originating point code related to the status ind */
  S16  status;    /* Status indicator. See defines below*/
  U8   priority;  /* Priority of this status indication   */
  U16  spare2;    /* Alignment                            */
} STAT_IND;

STAT_IND contains the following fields:

Field

Description

code

Whether an indication is data or status. Always M3UA_STAT_IND for status indications.

sapId

Service user identifier passed as suId in the ctaOpenServices call.

pc

Destination point code affected by this status indication.

opc

Originating point code affected by this status indication.

status

Status event that occurred:

StatPaused = Data traffic paused

StatResumed = Data traffic resumed

StatCongested = Data congested

StatUsrUnavail = User unavailable

StatCongestionEnds = Congestion ended

StatPrimary = M3UA is primary in a redundant configuration

StatBackup = M3UA is backup in a redundant configuration

StatStandAlone = M3UA is not in a redundant configuration

priority

Current congestion level for congestion-related indications. Valid range is 0 (lowest) through 3 (highest).