MTP3RetrieveMessage

Checks for and retrieves an incoming message from the MTP 3 layer.

Prototype

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

Argument

Description

ctahd

Natural Access handle.

pMsgInd

Pointer to 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.

Length

Pointer to buffer where the length of the indication is returned.


Return values

Return value

Description

MTP3_SUCCESS

 

MTP3_INVBOARD

Invalid board number.

MTP3_NOT_BOUND

ctaOpenServices not previously called.

MTP3_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;           /* MTP3_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

Whether an indication is data or status. Always MTP3_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. Possible values are 0 through 0xFFFFFF.

dpc

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

srvInfo

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

lnkSel

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

0 through 15 (ITU-T)

0 through 31 (ANSI)

0 through 255 (TUP only)

data

Data received.


Status indications

An application receives a STAT_IND structure when an important status change occurs on a circuit matching the application's service information octet. Status changes are generated by the local MTP 3 layer. For more information, refer to Receiving status indications.

typedef struct stat_ind_s 
{
  U8   code;      /* MTP3_STAT_IND (0x7A)                 */
  U8   spare1;    /* Alignment                            */
  U16  sapId;     /* Service user Id from Open Services   */
  U32  pc;        /* Point Code related to the status ind */
  S16  status;    /* Status indicator. See defines above  */
  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 MTP3_STAT_IND for status indications.

sapId

Service user identifier passed as suId in the ctaOpenServices call.

pc

Point code of the remote node affected by this status indication.

status

Status event that occurred:

StatPaused = Data traffic paused

StatResumed = Data traffic resumed

StatCongested = Data congested

StatUsrUnavail = User unavailable

StatRestart = Restart in progress

StatRestartEnd = Restart completed

StatCongestionEnds = Congestion ended

StatPrimary = MTP 3 is primary in redundant configuration

StatBackup = MTP 3 is backup in redundant configuration

StatStandAlone = MTP is not in a redundant configuration

priority

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


Extended status indications

If the application registered to receive extended status indications (using MTP3RegXStaReq), the application receives the XSTAT_IND structure when an important status change occurs on a link. The local MTP 3 layer generates status changes. For more information, refer to Receiving extended status indications.

type def struct xstat_ind_s 
{
  U8   code;    /* MTP3_XSTAT_IND (0x3A)              */
  U8   spare1;  /* Alignment                          */
  U16  sapId;   /* Service user Id from Open Services */
  U16  status;  /* Extended Status Type               */
  U16  link;    /* Affected MTP3 link                 */
  U16  spare2;  /* Reserved for future use            */
  U16  spare3;  /* Reserved for future use            */
} XSTAT_IND;

XSTAT_IND contains the following fields:

Field

Description

code

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

sapId

Service user identifier passed as suId in the ctaOpenServices call. Valid range is 0 through 15.

link

Link number of the affected MTP 3 link. Valid range is 0 to 31.

status

Status event that occurred:

XStatLinkUp = Link up

XStatLinkDown = Link down

XStatLinkInh = Link inhibited

XStatLinkInhDen = Link inhibit denied

XStatLinkUninh = Link uninhibited

XStatLinkUninhDen = Link uninhibit denied

XStatLinkRemBlock = Link remotely blocked

XStatLinkRemUnblock = Link remotely unblocked

XStatLinkLocBlock = Link locally blocked

XStatLinkLocUnblock = Link locally unblocked