Inside Macintosh: Open Transport /

Chapter 2 - Providers / Providers Reference

Constants and Data Types

Event Codes

Your application can include a notifier function that the provider calls to inform you that an asynchronous function has completed or that an asynchronous event has occurred. The provider passes an event code for the function's code parameter. The event code specifies the name of the asynchronous function that has completed or the name of an asynchronous event that has occurred. The provider can also pass information using the result and cookie parameters to the notifier function. Normally, if the provider calls your notifier because an asynchronous function has completed, the result parameter contains the result code for the function and the cookie parameter contains additional information whose meaning varies with the function called. For example, if you call the OTAsyncOpenEndpoint function, the cookie parameter would contain the endpoint reference for the endpoint provider you just opened.

Most of the codes specified by the event codes enumeration are used by endpoint providers and relate to the use of endpoint functions. You might need to read the "Endpoints" chapter in this book to make sense of the following constant name descriptions.

The constant names that the provider can use for the event code are given by the following enumeration:

enum {
   T_LISTEN                = (OTEventCode)0x0001,
   T_CONNECT               = (OTEventCode)0x0002,
   T_DATA                  = (OTEventCode)0x0004,
   T_EXDATA                = (OTEventCode)0x0008,
   T_DISCONNECT            = (OTEventCode)0x0010,
   T_ERROR                 = (OTEventCode)0x0020,
   T_UDERR                 = (OTEventCode)0x0040,
   T_ORDREL                = (OTEventCode)0x0080,
   T_GODATA                = (OTEventCode)0x0100,
   T_GOEXDATA              = (OTEventCode)0x0200,
   T_REQUEST               = (OTEventCode)0x0400,
   T_REPLY                 = (OTEventCode)0x0800,
   T_PASSCON               = (OTEventCode)0x1000,
   T_RESET                 = (OTEventCode)0x2000,
   T_BINDCOMPLETE          = (OTEventCode)0x20000001,
   T_UNBINDCOMPLETE        = (OTEventCode)0x20000002,
   T_ACCEPTCOMPLETE        = (OTEventCode)0x20000003,
   T_REPLYCOMPLETE         = (OTEventCode)0x20000004,
   T_DISCONNECTCOMPLETE    = (OTEventCode)0x20000005,
   T_OPTMGMTCOMPLETE       = (OTEventCode)0x20000006,
   T_OPENCOMPLETE          = (OTEventCode)0x20000007,
   T_GETPROTADDRCOMPLETE   = (OTEventCode)0x20000008,
   T_RESOLVEADDRCOMPLETE   = (OTEventCode)0x20000009,
   T_GETINFOCOMPLETE       = (OTEventCode)0x2000000A,
   T_SYNCCOMPLETE          = (OTEventCode)0x2000000B,
   T_MEMORYRELEASED        = (OTEventCode)0x2000000C,
   T_REGNAMECOMPLETE       = (OTEventCode)0x2000000D,
   T_DELNAMECOMPLETE       = (OTEventCode)0x2000000E,
   T_LKUPNAMECOMPLETE      = (OTEventCode)0x2000000F,
   T_LKUPNAMERESULT        = (OTEventCode)0x20000010,
   kOTProviderIsDisconnected= (OTEventCode)0x23000001,
   kOTProviderIsReconnected= (OTEventCode)0x23000002.
   kOTProviderWillClose    = (OTEventCode)0x24000001,
   kOTProviderIsClosed     = (OTEventCode)0x24000002,
   kOTConfigurationChanged = (OTEventCode)0x26000001,
};

Constant descriptions

T_LISTEN

A connection request has arrived. Call the OTListen function to read the request.

T_CONNECT

The passive peer has accepted a connection that you requested using the OTConnect function. Call the OTRcvConnect function to retrieve any data or option information that the passive peer has specified when accepting the function or to retrieve the address to which you are actually connected. The cookie parameter to the notifier function is the sndCall parameter that you specified when calling the OTConnect function.

T_DATA

Normal data has arrived. Depending on the mode of service you are using, you can call the OTRcvUData function or the OTRcv function to read it. Continue reading data until the function returns with the kOTNoDataErr result; you do not get another indication that data has arrived until you have read the entire unit.

T_EXDATA

Expedited data has arrived. Use the OTRcv function to read it. Continue reading data by calling the OTRcv function until the function returns with the kOTNoDataErr result; you do not get another indication that data has arrived until you have read the entire unit.

T_DISCONNECT

A connection has been torn down or rejected. Use the OTRcvDisconnect function to clear the event.

If the event is used to signify that a connection has been terminated, the cookie parameter to the notifier is NULL.

If the event indicates a rejected connection request, the cookie parameter to the notification routine is the same as the sndCall parameter that you passed to the OTConnect function.

T_UDERR

The provider was not able to send the data you specified using the OTSndUData function even though the function returned successfully. You must call the OTRcvUDErr function to clear this event and determine why the function failed.

T_ORDREL

The remote client has called the OTSndOrderlyDisconnect function to initiate an orderly disconnect. You must call the OTRcvOrderlyDisconnect function to acknowledge receiving the event and to retrieve any data that might have been sent with the disconnection request.

T_GODATA

Flow-control restrictions have been lifted. You can now send normal data.

T_GOEXDATA

Flow-control restrictions have been lifted. You can now send expedited data.

T_REQUEST

A request has arrived. Depending on the mode of service you are using, you can call the OTRcvRequest function or the OTRcvURequest function to receive it. You must continue to call the function until it returns with the kOTNoDataErr result.

T_REPLY

A response to a request has arrived. Depending on the mode of service you are using, you can call the OTRcvReply function or OTRcvUReply function to receive it. You must continue to call the function until it returns with the kOTNoDataErr result.

T_PASSCON

When the OTAccept function completes, the endpoint provider passes this event to the endpoint receiving the connection (whether that endpoint is the same as or different from the endpoint that calls the OTAccept function.) The cookie parameter contains the endpoint reference of the endpoint that called the OTAccept function.

T_RESET

A connection-oriented endpoint has received a reset from the remote end and has flushed all unread and unsent data. This only occurs for some types of endpoints, and generally leaves the endpoint in an unknown state.

T_BINDCOMPLETE

The OTBind function has completed. The cookie parameter contains the retAddr parameter of the bind call.

T_UNBINDCOMPLETE

The OTUnbind function has completed. The cookie parameter is meaningless.

T_ACCEPTCOMPLETE

The OTAccept function has completed. The cookie parameter contains the endpoint reference of the endpoint to which you passed off the connection.

T_REPLYCOMPLETE

The OTSndUReply or OTSndReply functions have completed. The cookie parameter contains the sequence number of the request retrieved with the OTRcvURequest or OTRcvRequest function.

T_DISCONNECTCOMPLETE

The OTSndDisconnect function has completed. The cookie parameter contains the call parameter of the OTSndDisconnect function.

T_OPTMGMTCOMPLETE

The OTOptionManagement function has completed. The cookie parameter contains the ret parameter that you have passed to the function.

T_OPENCOMPLETE

An asynchronous call to open a provider has completed. The cookie parameter contains the provider reference.

T_GETPROTADDRCOMPLETE

The OTGetProtAddress function has completed. The cookie parameter contains the peerAddr parameter that you passed to the OTGetProtocolAddress function. If you passed NULL for that parameter, the cookie parameter contains the address passed in the boundAddr parameter.

T_RESOLVEADDRCOMPLETE

The OTResolveAddress function has completed. The cookie parameter contains the retAddr parameter of the OTResolveAddress function.

T_GETINFOCOMPLETE

The OTGetEndpointInfo function has completed. The cookie parameter contains the info parameter of the OTGetEndpointInfo function.

T_SYNCCOMPLETE

The OTSync function has completed. The cookie parameter is meaningless.

T_MEMORYRELEASED

You are using an asynchronous endpoint that acknowledges sends and an OTSnd or OTSndUData function has completed and is done using the buffers containing the data you are sending. If you have called the OTSnd function, the cookie parameter contains the buf parameter. If you have called the OTSndUData function, the cookie parameter contains the udata parameter. The result parameter contains the number of bytes that were sent. This might be less than the number you meant to send due to flow-control or memory restrictions.

T_REGNAMECOMPLETE

The OTRegisterName function has completed. The cookie parameter contains the name parameter of the OTRegisterName function.

T_DELNAMECOMPLETE

The OTDeleteName function or the OTDeleteNameByID function has completed. The cookie parameter contains the name parameter or the id parameter of the function, respectively.

T_LKUPNAMECOMPLETE

The OTLookupName function has completed. The cookie parameter contains the reply parameter of the OTLookUpName function.

T_LKUPNAMERESULT

An OTLookupName function has found a name and is returning it, but the lookup is not yet complete. The cookie parameter contains the reply parameter passed to the OTLookupName function.

kOTProviderIsDisconnected

Your provider was bound with qlen parameter value greater than 0 and it has been disconnected (is no longer listening). You receive this event after a port has accepted a request to temporarily yield ownership of a port to another provider, which causes this provider to be disconnected from the port in question. This currently only happens with serial ports, but could also happen with other connection-oriented drivers that have characteristics similar to serial ports. You get a kOTProviderIsReconnected message when the port reverts back to this provider's ownership again.

kOTProviderIsReconnected

Your provider has been reconnected, that is, the cause for its disconnection has been relieved.

kOTProviderWillClose

When you return from the notifier function, Open Transport will close the provider whose reference is contained in the cookie parameter. The result parameter contains a code specifying the reason why the provider had to close. For example, the user decided to switch links using the control panel.

You can only get this event at system task time. Consequently, you are allowed to set the endpoint to synchronous mode (from within the notifier function) and call functions synchronously before you return from the notifier, at which point, the provider is closed. At this point, any calls other than OTCloseProvider will fail with a kOTOutStateErr.

kOTProviderIsClosed

The provider has closed. The reason for being closed can be found in the OTResult value passed to your notifier. The reasons typically are kOTPortHasDiedErr, kOTPortWasEjectedErr, or kOTPortLostConnectionErr. At this point, any calls other than OTCloseProvider will fail with a kOTOutStateErr.