TUPRetrieveMessage

Retrieves the next message from the TUP layer or optionally waits for a message if none is currently available.

Prototype

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
{
    U8 indType;         /* indic/confirm type                    */
    U8 evntType;        /* event type for release, status, and
                        /* connection status indications         */
    SuId suId;          /* service user (SAP) id - all           */
    TupInstId suInstId; /* caller's reference number - all       */
    TupInstId spInstId; /* TUP's reference number - all          */
    CirIdx circuit;     /* circuit index - all                   */
} TupRcvInfoBlk;


Return values

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.


Details

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

TupConRspEvnt

EVTTUPCONIND

TupConEvnt

EVTTUPCNSTIND

TupCnStEvnt

EVTTUPRELIND

TupRelEvnt

EVTTUPRELCFM

TupRelEvnt

EVTTUPSTAIND

TupStaEvnt

EVTTUPMGTSTAIND

TupStaEvnt


 

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.