Retrieves the next message from the TUP layer or optionally waits for a message if none is currently available.
DWORD NMSAPI TUPRetrieveMessage ( CTAHD ctahd, TupAllSdus *event, TupRcvInfoBlk *infoBlk)
Argument |
Description |
ctahd |
Natural Access handle. |
event |
Pointer to the address of the caller's event buffer where the received event (if any) is returned to the caller. |
infoBlk |
Pointer to the address of the caller's receive information block where information regarding the received event (if any) is returned to the caller: typedef struct rcvInfoBlk |
Return value |
Description |
TUP_SUCCESS |
|
TUP_NOMSG |
No event messages waiting. |
TUP_NOTBOUND |
Application failed to open the TUP service. |
TUP_RESOURCES |
Could not allocate message buffer. |
Periodically call this function to receive events (messages) from the TUP layer.
When a message is received, TUPRetrieveMessage copies the event to the caller's event buffer and performs any necessary byte order translation to convert to the host's native byte ordering. Information about the event is returned to the caller in the infoBlk parameter.
The caller's event buffer must be large enough to accommodate any of the events, as defined by the TupAllSdus structure (union of all event structures). The actual event structure returned (which is a member of the union) depends on the value of the infoBlk.indType field returned, as shown in the following table:
Indication type |
Event structure employed |
EVTTUPCONCFM |
|
EVTTUPCONIND |
|
EVTTUPCNSTIND |
|
EVTTUPRELIND |
|
EVTTUPRELCFM |
|
EVTTUPSTAIND |
|
EVTTUPMGTSTAIND |
The indication type (indType) identifies the event received and is coded to one of the following values:
Indication type |
Hex |
Description |
EVTTUPCONCFM |
0x0D |
Connect confirm |
EVTTUPCONIND |
0x0E |
Connect indication |
EVTTUPCNSTIND |
0x5A |
Connect status indication |
EVTTUPRELIND |
0x5E |
Connect release indication |
EVTTUPRELCFM |
0x5D |
Connect release confirmation |
EVTTUPSTAIND |
0x7A |
Status indication |
EVTTUPMGTSTAIND |
0x7B |
Local management status indication |
The event type (evntType) identifies the actual message received for status and connection status indications. It is coded to one of the values in the following tables.
For connection status indications:
Event type |
Description |
TUPADDRCMPLT |
Address complete (ACM) |
TUPFRWDTRSFR |
Forward transfer (FOT) |
TUPINFORMATION |
Information (response to INFORMATREQ, GSM) |
TUPINFORMATREQ |
Information request (GRQ) |
TUPSUBSADDR |
Subsequent address message (SAM) |
TUPSUBSADDRONE |
Single subsequent address (SAO) |
TUPREANSWER |
Re-answer signal (RAN) |
TUPCALLCLEAR |
Calling party clear (CCL) |
TUPAUTOCONG |
Auto-congestion message (ACC) |
TUPOPERATOR |
Operator signal (OPR) - China only |
TUP METERPULSE |
Metering pulse message (MPM) - China only |
TUPMALICIOUS |
Malicious call signal (MAL) - China only |
For status indications (including local management indications):
Event type |
Description |
TUPREATTEMPT |
Re-attempt indication |
TUPERRORIND |
Error indication |
TUPCONFUSION |
Confusion indication |
TUPCONTCHK |
Continuity check (CCR) |
TUPCONTREP |
Continuity report (COT) |
TUPCONFAIL |
Continuity report (CCF) |
TUPCIRBLKREQ |
Circuit block request (BLO) |
TUPCIRUNBLKREQ |
Circuit unblock request (UBL) |
TUPCIRRESREQ |
Circuit reset request (RSC) |
TUPCRMGRPBLKREQ |
Maintenance circuit group block request (MGB) |
TUPCRMGRPUNBLKREQ |
Maintenance circuit group unblock request (MGU) |
TUPCRHGRPBLKREQ |
Hardware circuit group block request (HGB) |
TUPCRHGRPUNBLKREQ |
Hardware circuit group unblock request (HGU) |
TUPCRSGRPBLKREQ |
Software circuit group block request (SGB) |
TUPCRSGRPUNBLKREQ |
Software circuit group unblock request (SGU) |
TUPCIRGRPRESREQ |
Circuit group reset request (GRS) |
TUPSWITCHCONG |
Switch equipment congestion (CNG) |
TUPCIRCUITCONG |
Circuit group congestion (CGC) |
TUPNATIONALCONG |
Nation network congestion (NNC) |
TUPADDRESSINCOMP |
Address incomplete (ADI) |
TUPCALLFAILURE |
Call failure (CFL) |
TUPSUBBUSY |
Subscriber busy (SSB) |
TUPUNALLOCATEDNUM |
Unallocated number (UNN) |
TUPOUTOFSERVICE |
Line out of service (LOS) |
TUPSENDSPECIAL |
Send a special tone (SST) |
TUPACCESSBARRED |
Access barred (ACB) |
TUPNODIGITAL |
Digital path not provided (DPN) |
TUPEXTENDEDINFO |
Extended unsuccessful message (EUM) |
TUPCLEARBKW |
Clear backwards (CBK) |
TUPMISDIALEDPREFIX |
Misdialed trunk prefix (MPR) - not supported in China |
TUPSUBLOCALBUSY |
Subscriber local busy (SLB) - China only |
TUPSUBTOLLBUSY |
Subscriber toll busy (STB) - China only |
TUPDUALSEIZURE |
Call failed due to incoming call |
The application must save the service provider instance ID (spInstId) field from the first event received from TUP for each connection and use it in subsequent requests associated with that connection.
For more information, refer to Operating system specific considerations.