Applications receive confirmations (responses) and indications of far-end initiated requests by periodically calling TUPRetrieveMessage. This function checks for an incoming message and returns an indication of whether or not a message is available. When an incoming message is received, TUPRetrieveMessage:
Copies the event structure to the buffer provided by the caller
Performs any byte-order translation between network byte order and host byte order
Reports which event was received back to the calling application
The application must periodically call this function to receive messages from the TUP layer.
To allow applications more flexibility in handling multiple devices, mechanisms are provided to allow the calling application to be notified when a TUP message is available for it without having to poll the TX board by periodically calling TUPRetrieveMessage.
In a multiple-threaded application, any thread can generate a request. However, a single receiver thread must receive all asynchronous events from the TUP layer (incoming calls, status indications, and so on) and route them to the proper transaction thread based on the circuit, service user instance ID, or other transaction information.
For example, in an application consisting of a main thread that spawns a child call thread whenever it wants to initiate a call, the call thread is responsible for initiating TUPConnectReq, collecting the responses from the receiver thread, and taking the appropriate action. The application can have many simultaneous calls and call threads active at any given time.
Multiple call threads can generate the transaction requests in any order. The requests are processed by the TUP layer in the order they are received. If each call thread then calls TUPRetrieveMessage to retrieve the response to its transaction request, there is no guarantee that the TUP message returned by TUPRetrieveMessage would be associated with the calling thread's call. The first thread to call TUPRetrieveMessage when a message is pending receives the first pending message, regardless of the transaction with which it is associated. The incoming message can be a new call request from a far service switching point or a network status indication message.
Instead, the main thread itself or a separate child receiver thread is the only caller of TUPRetrieveMessage. It can then analyze each incoming event and either route it to the proper child call thread or, in the case of a new incoming call, create a new child call thread to handle the incoming call request.