Checks for and retrieves an incoming message from the MTP 3 layer.
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 value |
Description |
MTP3_SUCCESS |
|
MTP3_INVBOARD |
Invalid board number. |
MTP3_NOT_BOUND |
ctaOpenServices not previously called. |
MTP3_NO_MSG |
No message currently waiting. |
To process incoming messages, the application can perform one of the following tasks:
Call MTP3RetrieveMessage periodically within a polling process. The application must poll regularly to avoid excessive queuing of messages in the TX driver or the MTP 3 task.
Wait for an asynchronous notification that a message is available, and then call MTP3RetrieveMessage to retrieve it.
Applications can receive the following types of messages:
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. |
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). |
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 |