Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Networking With Open Transport / Part 2 - Open Transport Reference
Chapter 21 - Providers Reference / Constants and Data Types

Event Codes

Your application can include a notifier function that the provider calls to inform you that some provider event has occurred. The provider passes an event code for the function's code parameter. The event code specifies which provider event 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. See "Handling Events for Endpoints" for more information.

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,
   kOTSyncIdleEvent
   kOTProviderIsReconnected  = (OTEventCode)0x23000002.
   kOTProviderWillClose      = (OTEventCode)0x24000001,
   kOTProviderIsClosed       = (OTEventCode)0x24000002,
};
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 connection 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 type of service of the endpoint 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 will not get another indication that data has arrived until you have read all the data and got this error.
T_ERROR
Obsolete.
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 will not get another indication that data has arrived until you have read all the data and got this error.
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.
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 type of service for the endpoint 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 type of service of the endpoint 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 resRef parameter to 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 it 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 resRef parameter to the OTAccept function.
T_REPLYCOMPLETE
The OTSndUReply or OTSndReply functions have completed. The cookie parameter contains the sequence number used in the OTSndUReply or OTSndReply call.
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 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 Open Transport is done using the buffers containing the data you are sending. If you called the OTSnd function, the cookie parameter contains the buf parameter. If you 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.
You should not wait for the T_MEMORYRELEASED event from a previous send operation to trigger more sends. The exact time this event occurs depends on how the underlying provider is implemented. It might hold on to memory until the next send occurs, or behave in some other way which causes it to delay releasing memory.
Note that T_MEMORYRELEASED events can reenter your notifier. See "OTAckSends" for more information.
T_REGNAMECOMPLETE
The OTRegisterName function has completed. The cookie parameter is the reply parameter, unless it was NULL. In this case, it is the req parameter.
T_DELNAMECOMPLETE
The OTDeleteName function or the OTDeleteNameByID function has completed. The cookie parameter contains the name parameter or the nameId 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.
kOTSyncIdleEvent
A synchronous call is waiting to complete. Call the function YieldToAnyThread from your notifier to allow other concurrent processes to obtain processing time. See "Using Synchronous Processing With Threads" for more information.
kOTProviderIsDisconnected
Your provider was bound with a 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 result code specifying the reason why the provider had to close. For example, the user decided to switch links using the TCP/IP or AppleTalk control panel. The result codes that can be returned are in the range -3280 through -3285; these are documented in "Result Codes".
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. After this, 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.
Previous Book Contents Book Index Next

© Apple Computer, Inc.
15 JAN 1998