Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

< Previous PageNext Page > Hide TOC

Deprecated Open Transport Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

CloseOpenTransportInContext

Unregisters your application or code resource connection to Open Transport. (Deprecated in Mac OS X v10.4.)

void CloseOpenTransportInContext (
   OTClientContextPtr clientContext
);

Parameters
clientContext
Availability
Carbon Porting Notes

The CloseOpenTransportinContext function acts like the pre-Carbon CloseOpenTransport function except that it takes an additional parameter, an OTClientContextPtr, which can be NULL for applications. Other types of clients must provide a valid client context pointer.

Declared In
OpenTransport.h

DisposeOTListSearchUPP

Disposes of a universal procedure pointer (UPP) to a list search callback. (Deprecated in Mac OS X v10.4.)

void DisposeOTListSearchUPP (
   OTListSearchUPP userUPP
);

Parameters
userUPP
Availability
Declared In
OpenTransport.h

DisposeOTNotifyUPP

Disposes of a universal procedure pointer (UPP) to a notification callback. (Deprecated in Mac OS X v10.4.)

void DisposeOTNotifyUPP (
   OTNotifyUPP userUPP
);

Parameters
userUPP
Availability
Declared In
OpenTransport.h

DisposeOTProcessUPP

Disposes of a universal procedure pointer (UPP) to a process callback. (Deprecated in Mac OS X v10.4.)

void DisposeOTProcessUPP (
   OTProcessUPP userUPP
);

Parameters
userUPP
Availability
Declared In
OpenTransport.h

InitOpenTransportInContext

Initializes the parts of Open Transport for use by the application or code resource. (Deprecated in Mac OS X v10.4.)

OSStatus InitOpenTransportInContext (
   OTInitializationFlags flags,
   OTClientContextPtr *outClientContext
);

Parameters
flags

Tells Open Transport whether your code is an application or a plug-in.

outClientContext

Returns the client context pointer.

Return Value

A result code. See “Open Transport Result Codes.”

Discussion

In Carbon, the InitOpenTransportInContext function acts like the pre-Carbon InitOpenTransport function, except that it takes parameters that specify initialization context explicitly.

Use the flags parameter to tell Open Transport whether your code is an application or some other target (for example, a plug-in that runs in an application context but is not the application itself). The second parameter returns the client context pointer, which you must pass to other asset-creation routines. For more information, see Understanding Open Transport Asset Tracking at http://developer.apple.com/technotes/tn/tn1173.html.

Availability
Declared In
OpenTransport.h

InvokeOTListSearchUPP

Calls a list search callback. (Deprecated in Mac OS X v10.4.)

Boolean InvokeOTListSearchUPP (
   const void *ref,
   OTLink *linkToCheck,
   OTListSearchUPP userUPP
);

Parameters
ref
linkToCheck
userUPP
Availability
Declared In
OpenTransport.h

InvokeOTNotifyUPP

Calls a notification callback. (Deprecated in Mac OS X v10.4.)

void InvokeOTNotifyUPP (
   void *contextPtr,
   OTEventCode code,
   OTResult result,
   void *cookie,
   OTNotifyUPP userUPP
);

Parameters
contextPtr
code
result
cookie
userUPP
Availability
Declared In
OpenTransport.h

InvokeOTProcessUPP

Calls a process callback. (Deprecated in Mac OS X v10.4.)

void InvokeOTProcessUPP (
   void *arg,
   OTProcessUPP userUPP
);

Parameters
arg
userUPP
Availability
Declared In
OpenTransport.h

NewOTListSearchUPP

Creates a new universal procedure pointer (UPP) to a list search callback. (Deprecated in Mac OS X v10.4.)

OTListSearchUPP NewOTListSearchUPP (
   OTListSearchProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the OTListSearchUPP data type.

Availability
Declared In
OpenTransport.h

NewOTNotifyUPP

Creates a new universal procedure pointer (UPP) to a notification callback. (Deprecated in Mac OS X v10.4.)

OTNotifyUPP NewOTNotifyUPP (
   OTNotifyProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the OTNotifyUPP data type.

Availability
Declared In
OpenTransport.h

NewOTProcessUPP

Creates a new universal procedure pointer (UPP) to a process callback. (Deprecated in Mac OS X v10.4.)

OTProcessUPP NewOTProcessUPP (
   OTProcessProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the OTProcessUPP data type.

Availability
Declared In
OpenTransport.h

OTAccept

Accepts an incoming connection request. (Deprecated in Mac OS X v10.4.)

OSStatus OTAccept (
   EndpointRef listener,
   EndpointRef worker,
   TCall *call
);

Parameters
listener
worker
call
Return Value

A result code. See “Open Transport Result Codes.”

Availability
Declared In
OpenTransport.h

OTAckSends

Specifies that a provider make an internal copy of data being sent and that it notify you when it has finished sending data. (Deprecated in Mac OS X v10.4.)

OSStatus OTAckSends (
   ProviderRef ref
);

Parameters
ref
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

By default, providers make an internal copy of data before sending it and they do not acknowledge sends. If you use the OTAckSends function to specify that the provider acknowledge sends and you call a function that sends data, the provider does not copy the data before sending it. Instead, it reads data directly from your buffer while sending. For this reason, you must not change the contents of your buffer until the provider is no longer using it. The provider lets you know that it has finished using the buffer by calling your notifier function and passing T_MEMORYRELEASED event code for the code parameter, a pointer to the buffer that was sent in the cookie parameter, and the size of the buffer in the result parameter.

If you have not installed a notifier function for the provider, this function returns the kOTAccessErr result.

Availability
Declared In
OpenTransport.h

OTAddFirst

Places a link at the front of a FIFO list. (Deprecated in Mac OS X v10.4.)

void OTAddFirst (
   OTList *list,
   OTLink *link
);

Parameters
list
link
Availability
Declared In
OpenTransport.h

OTAddLast

Adds a link to the end of a FIFO list. (Deprecated in Mac OS X v10.4.)

void OTAddLast (
   OTList *list,
   OTLink *link
);

Parameters
list
link
Availability
Declared In
OpenTransport.h

OTAllocInContext

Allocates a data structure of a specified type. (Deprecated in Mac OS X v10.4.)

void * OTAllocInContext (
   EndpointRef ref,
   OTStructType structType,
   UInt32 fields,
   OSStatus *err,
   OTClientContextPtr clientContext
);

Parameters
ref
structType
fields
err
clientContext
Discussion

In general, Apple recommends that you avoid the OTAllocInContext call because using it extensively causes your program to allocate and deallocate many memory blocks, with each extra memory allocation costing time.

Under Carbon, OTAllocInContext takes a client context pointer. Applications may pass NULL after calling InitOpenTransport(kInitOTForApplicationMask, ...). Non-applications must always pass a valid client context.

Availability
Declared In
OpenTransport.h

OTAllocMemInContext

Allocates memory using an explicit client context. (Deprecated in Mac OS X v10.4.)

void * OTAllocMemInContext (
   OTByteCount size,
   OTClientContextPtr clientContext
);

Parameters
size
clientContext
Availability
Declared In
OpenTransport.h

OTAsyncOpenAppleTalkServicesInContext

Opens an asynchronous AppleTalk service provider in context. (Deprecated in Mac OS X v10.4.)

OSStatus OTAsyncOpenAppleTalkServicesInContext (
   OTConfigurationRef cfig,
   OTOpenFlags flags,
   OTNotifyUPP proc,
   void *contextPtr,
   OTClientContextPtr clientContext
);

Parameters
cfig
flags
proc
contextPtr
clientContext
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

Applications may pass a NULL context pointer but nonapplications must always pass a valid client context pointer.

You receive a client context pointer when you call the function InitOpenTransportInContext.

Availability
Declared In
OpenTransportProviders.h

OTAsyncOpenEndpointInContext

Opens an endpoint and installs a notifier callback function for the endpoint. (Deprecated in Mac OS X v10.4.)

OSStatus OTAsyncOpenEndpointInContext (
   OTConfigurationRef config,
   OTOpenFlags oflag,
   TEndpointInfo *info,
   OTNotifyUPP upp,
   void *contextPtr,
   OTClientContextPtr clientContext
);

Parameters
config
oflag
info
upp
contextPtr
clientContext
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

Applications may pass a NULL context pointer but nonapplications must always pass a valid client context pointer.

You receive a client context pointer when you call the function InitOpenTransportInContext.

Availability
Declared In
OpenTransport.h

OTAsyncOpenInternetServicesInContext

Opens the TCP/IP service provider and returns an Internet services reference. (Deprecated in Mac OS X v10.4.)

OSStatus OTAsyncOpenInternetServicesInContext (
   OTConfigurationRef cfig,
   OTOpenFlags oflag,
   OTNotifyUPP upp,
   void *contextPtr,
   OTClientContextPtr clientContext
);

Parameters
cfig
oflag
upp
contextPtr
clientContext
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

Applications may pass a NULL context pointer but nonapplications must always pass a valid client context pointer.

You receive a client context pointer when you call the function InitOpenTransportInContext.

Availability
Declared In
OpenTransportProviders.h

OTAsyncOpenMapperInContext

Creates an asynchronous mapper and installs a notifier function for the mapper provider. (Deprecated in Mac OS X v10.4.)

OSStatus OTAsyncOpenMapperInContext (
   OTConfigurationRef config,
   OTOpenFlags oflag,
   OTNotifyUPP upp,
   void *contextPtr,
   OTClientContextPtr clientContext
);

Parameters
config
oflag
upp
contextPtr
clientContext
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

Applications may pass a NULL context pointer but nonapplications must always pass a valid client context pointer.

You receive a client context pointer when you call the function InitOpenTransportInContext.

Availability
Declared In
OpenTransport.h

OTATalkGetInfo

Obtains information about the AppleTalk environment for a given node. (Deprecated in Mac OS X v10.4.)

OSStatus OTATalkGetInfo (
   ATSvcRef ref,
   TNetbuf *info
);

Parameters
ref
info
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

The OTATalkGetInfo function returns the information contained in the AppleTalkInfo data structure that describes your current AppleTalk environment. This includes your network number and node ID, the network number and node ID of a local router, and the current network range for the extended network to which the machine is connected.

If you execute this function asynchronously, Open Transport calls your notifier with a T_GETATALKINFOCOMPLETE completion event to signal the function’s completion and uses your notifier’s cookie parameter for the AppleTalk information. The cookie parameter actually holds a pointer to a TNetbuf structure, which points in turn to a buffer containing the AppleTalkInfo structure. The maximum size of this buffer is 22 bytes.

If the machine is multihomed—that is, if multiple network numbers and node numbers are associated with the same machine—the OTATalkGetInfo function returns information about the node whose network number and node ID are selected in the AppleTalk control panel.

Availability
Declared In
OpenTransportProviders.h

OTATalkGetLocalZones

Obtains a list of the zones available on your network. (Deprecated in Mac OS X v10.4.)

OSStatus OTATalkGetLocalZones (
   ATSvcRef ref,
   TNetbuf *zones
);

Parameters
ref
zones
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

The OTATalkGetLocalZones function returns a list of the zone names in your application’s network if it is an extended network. These are all the zones to which your node can belong. If your application is in a nonextended network, this function returns only one zone name, the same one returned by the OTATalkGetMyZone function.

If you execute this function asynchronously, Open Transport calls your notifier function with a T_GETLOCALZONESCOMPLETE completion event to signal the function’s completion and uses your notifier’s cookie parameter for the list of zones. The cookie parameter actually holds a pointer to a TNetbuf structure, which points to a buffer containing a list of zone names, each of which is stored as a Pascal-style string. Using a Pascal-style string for the zone name is redundant since you can determine the length of the string from the maxlen field of the TNetbuf structure, but the other zone-related calls use Pascal-style strings, so this call also uses them for consistency.

Each string can be up to 32 characters in length, and if you add a length byte, each can have a maximum size of 33 bytes. As there can be a maximum of 254 zones on an extended network, the maximum size of the buffer is 8382 bytes.

Because zone names are often less than 32 characters long and AppleTalk service providers don’t pad short names, 6 KB bytes is likely to be a safe value for the buffer’s size, defined by the TNetbuf->maxlen field.

Availability
Declared In
OpenTransportProviders.h

OTATalkGetMyZone

Obtains the AppleTalk zone name of the node on which your application is running. (Deprecated in Mac OS X v10.4.)

OSStatus OTATalkGetMyZone (
   ATSvcRef ref,
   TNetbuf *zone
);

Parameters
ref
zone
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

The OTATalkGetMyZone function gets the name of your application’s AppleTalk zone. If you call this function asynchronously, Open Transport calls your application’s notifier with a T_GETMYZONECOMPLETE completion event to signal the function’s completion and uses your notifier’s cookie parameter for the zone name. More precisely, the cookie parameter points to a TNetbuf structure that in turn points to a buffer containing the zone name, which is stored as a Pascal-style string. The string can be up to 32 characters in length, so with the addition of a length byte, the buffer can have a maximum size of 33 bytes. Using a Pascal-style string for the zone name is redundant since you can determine the length of the string from the maxlen field of the TNetbuf structure, but the other zone-related calls use Pascal-style strings, so this call also uses them for consistency.

Availability
Declared In
OpenTransportProviders.h

OTATalkGetZoneList

Obtains a list of all the zones available on the AppleTalk internet. (Deprecated in Mac OS X v10.4.)

OSStatus OTATalkGetZoneList (
   ATSvcRef ref,
   TNetbuf *zones
);

Parameters
ref
zones
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

The OTATalkGetZoneList function returns a list of all the zones on the AppleTalk internet to which your network belongs.

If you execute this function asynchronously, Open Transport calls your notifier function with a T_GETZONELISTCOMPLETE completion event to signal the function’s completion and uses your notifier’s cookie parameter for the list of zones. The cookie parameter actually holds a pointer to a TNetbuf structure, which points to a buffer containing a list of zone names, each of which is a Pascal-style string. Using a Pascal-style string for the zone name is redundant since you can determine the length of the string from the maxlen field of the TNetbuf structure, but the other zone-related calls use Pascal-style strings, so this call also uses them for consistency.

Each string can be up to 32 characters in length, and if you add a length byte, each can have a maximum size of 33 bytes. As AppleTalk internets can have a number of extended networks, you need to allocate a buffer (using the TNetbuf->maxlen field) that holds as much as 64 KB of memory. To keep the buffer size as small and efficient as possible, you can set up a large buffer, test for the kOTBufferOverflowErr error, and then increase the size of the buffer and reissue the call if this error is returned.

Availability
Declared In
OpenTransportProviders.h

OTAtomicAdd16

Atomically adds a 16-bit value to a memory location. (Deprecated in Mac OS X v10.4.)

SInt16 OTAtomicAdd16 (
   SInt32 toAdd,
   SInt16 *dest
);

Parameters
toAdd
dest
Availability
Declared In
OpenTransport.h

OTAtomicAdd32

Atomically adds a 32-bit value to a memory location. (Deprecated in Mac OS X v10.4.)

SInt32 OTAtomicAdd32 (
   SInt32 toAdd,
   SInt32 *dest
);

Parameters
toAdd
dest
Availability
Declared In
OpenTransport.h

OTAtomicAdd8

Atomically adds an 8-bit value to a memory location. (Deprecated in Mac OS X v10.4.)

SInt8 OTAtomicAdd8 (
   SInt32 toAdd,
   SInt8 *dest
);

Parameters
toAdd
dest
Availability
Declared In
OpenTransport.h

OTAtomicClearBit

Clears a bit in a byte. (Deprecated in Mac OS X v10.4.)

Boolean OTAtomicClearBit (
   UInt8 *bytePtr,
   OTByteCount bitNumber
);

Parameters
bytePtr
bitNumber
Availability
Declared In
OpenTransport.h

OTAtomicSetBit

Sets a specified bit in a byte. (Deprecated in Mac OS X v10.4.)

Boolean OTAtomicSetBit (
   UInt8 *bytePtr,
   OTByteCount bitNumber
);

Parameters
bytePtr
bitNumber
Availability
Declared In
OpenTransport.h

OTAtomicTestBit

Tests a bit in a byte and returns its current state. (Deprecated in Mac OS X v10.4.)

Boolean OTAtomicTestBit (
   UInt8 *bytePtr,
   OTByteCount bitNumber
);

Parameters
bytePtr
bitNumber
Availability
Declared In
OpenTransport.h

OTBind

Assigns an address to an endpoint. (Deprecated in Mac OS X v10.4.)

OSStatus OTBind (
   EndpointRef ref,
   TBind *reqAddr,
   TBind *retAddr
);

Parameters
ref
reqAddr

If you specify NIL for the reqAddr parameter, Open Transport chooses a protocol address for you and requests 0 as the endpoint’s maximum number of concurrent outstanding connect indications.

If you want Open Transport to assign an address for you, setthe addr.len field of the TBind structure to 0.

retAddr

You can set this parameter to nil if you do not care to know what address the endpoint is bound to or what the negotiated value of qlen is.

Return Value

A result code. See “Open Transport Result Codes.”

Discussion

You call the OTBind function to request an address that an endpoint be bound to. You can either use the reqAddr parameter to request that the endpoint be bound to a specific address or allow the endpoint provider to assign an address dynamically by passing nil for this parameter. Consult the documentation for the top-level protocol you are using to determine whether it is preferable to have the address assigned dynamically. The function returns the address to which the endpoint is actually bound in the retAddr parameter. This might be different from the address you requested, if you requested a specific address.

If you are binding a connection-oriented endpoint, you must use the reqAddr->qlen field to specify the number of connection requests that may be outstanding for this endpoint. The retAddr->qlen field specifies, on return, the actual number of connection requests allowed for the endpoint. This number might be smaller than the number you requested. Note that when the endpoint is actually connected, the number might be further decreased by negotiations taking place at that time.

If you call the OTBind function asynchronously and you have not installed a notifier function, the only way to determine when the function completes is to poll the endpoint using the OTGetEndpointState function. This function returns a kOTStateChangeErr until the bind completes. When the endpoint is bound, the state is either T_UNBND if the bind failed, or T_IDLE if it succeeded.

You can cancel an asynchronous bind that is still in progress by calling the OTUnbind function.

You must not bind more than one connectionless endpoint to a single address. Some connection-oriented protocols let you bind two or more endpoints to the same address. In such instances, you must use only one of the endpoints to listen for connection requests for that address. When binding the endpoint listening for a connection, you must set the reqAddr->qlen field of the OTBind function to a value greater than or equal to 1. When binding the other endpoints, you must set the reqAddr->qlen field to 0.

If you accept a connection for an endpoint that is also listening for connection requests, the address of that endpoint is deemed “busy” for the duration of the connection, and you must not bind another endpoint for listening to that same address. This requirement prevents more than one endpoint bound to the same address from accepting connection requests. If you have to bind another listening endpoint to the same address, you must first use the OTUnbind function to unbind the first endpoint or use the OTCloseProvider function to close it.

Availability
Declared In
OpenTransport.h

OTBufferDataSize

Obtains the size of the no-copy receive buffer. (Deprecated in Mac OS X v10.4.)

OTByteCount OTBufferDataSize (
   OTBuffer *buffer
);

Parameters
buffer
Return Value

See the description of the OTByteCount data type.

Availability
Declared In
OpenTransportProtocol.h

OTCancelSynchronousCalls

Cancels any currently executing synchronous function for a specified provider. (Deprecated in Mac OS X v10.4.)

OSStatus OTCancelSynchronousCalls (
   ProviderRef ref,
   OSStatus err
);

Parameters
ref
err
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

The OTCancelSynchronousCalls function cancels any currently executing synchronous function for the provider that you specify. The provider need not be in synchronous mode when you call this function.

Typically, you would call the OTCancelSynchronousCalls function at interrupt time by installing a Time Manager task that executes after a given amount of time has passed. You could do this to prevent a synchronous function from hanging the system.

Availability
Declared In
OpenTransport.h

OTCancelTimerTask

Cancels a task that was already scheduled for execution. (Deprecated in Mac OS X v10.4.)

Boolean OTCancelTimerTask (
   OTTimerTask timerTask
);

Parameters
timerTask
Availability
Declared In
OpenTransportProtocol.h

OTCanMakeSyncCall

Checks whether you can call a synchronous function. (Deprecated in Mac OS X v10.4.)

Boolean OTCanMakeSyncCall (
   void
);

Parameters
Availability
Declared In
OpenTransport.h

OTClearBit

Clears a bit atomically. (Deprecated in Mac OS X v10.4.)

Boolean OTClearBit (
   UInt8 *bitMap,
   OTByteCount bitNo
);

Parameters
bitMap
bitNo
Discussion

OTClearBit is available to client and kernel code, but only to native architecture clients.

Availability
Declared In
OpenTransportProtocol.h

OTCloneConfiguration

Copies an OTConfiguration structure. (Deprecated in Mac OS X v10.4.)

OTConfigurationRef OTCloneConfiguration (
   OTConfigurationRef cfig
);

Parameters
cfig
Return Value

See the description of the OTConfigurationRef data type.

Discussion

The OTCloneConfiguration function copies the OTConfiguration structure that you specify in the cfig parameter and returns a pointer to the copy. Because the internal format of an OTConfiguration structure is private, you must use the OTCloneConfiguration function to obtain two identical structures. For example, you can use this function when another application passes you a configuration structure that you want to reuse but for which you do not have the original configuration string. By cloning the structure, you have access to an additional copy of the configuration even without knowing its configuration string.

Availability
Declared In
OpenTransport.h

OTCloseProvider

Closes a provider of any type—endpoint, mapper, or service provider. (Deprecated in Mac OS X v10.4.)

OSStatus OTCloseProvider (
   ProviderRef ref
);

Parameters
ref
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

The OTCloseProvider function closes the provider that you specify in the ref parameter. Closing the provider deletes all memory reserved for it in the system heap, deletes its resources, and cancels any provider functions that are currently executing.

Open Transport does not guarantee that all outstanding functions have completed before it closes the provider. It is ultimately your responsibility to make sure that all provider functions that you care about have finished executing, before you close and delete a provider.

Availability
Declared In
OpenTransport.h

OTCompareAndSwap16

Atomically compares two 16-bit values and changes one of these values if they are the same. (Deprecated in Mac OS X v10.4.)

Boolean OTCompareAndSwap16 (
   UInt32 oldValue,
   UInt32 newValue,
   UInt16 *dest
);

Parameters
oldValue
newValue
dest
Availability
Declared In
OpenTransport.h

OTCompareAndSwap32

Atomically compares two 32-bit values and changes one of these values if they are the same. (Deprecated in Mac OS X v10.4.)

Boolean OTCompareAndSwap32 (
   UInt32 oldValue,
   UInt32 newValue,
   UInt32 *dest
);

Parameters
oldValue
newValue
dest
Availability
Declared In
OpenTransport.h

OTCompareAndSwap8

Atomically compares two 8-bit values and changes one of these values if they are the same. (Deprecated in Mac OS X v10.4.)

Boolean OTCompareAndSwap8 (
   UInt32 oldValue,
   UInt32 newValue,
   UInt8 *dest
);

Parameters
oldValue
newValue
dest
Availability
Declared In
OpenTransport.h

OTCompareAndSwapPtr

Atomically compares the value of a pointer at a memory location and atomically swaps it with a second pointer value if the compare is successful. (Deprecated in Mac OS X v10.4.)

Boolean OTCompareAndSwapPtr (
   void *oldValue,
   void *newValue,
   void **dest
);

Parameters
oldValue
newValue
dest
Availability
Declared In
OpenTransport.h

OTCompareDDPAddresses

Compares two DDP address structures. (Deprecated in Mac OS X v10.4.)

Boolean OTCompareDDPAddresses (
   const DDPAddress *addr1,
   const DDPAddress *addr2
);

Parameters
addr1
addr2
Discussion

The OTCompareDDPAddresses function compares two DDP addresses for equality and returns true if the two addresses match. It cannot compare NBP or combined DDP-NBP addresses; using these address types always returns false. This function uses the zero-matches-anything AppleTalk rule when doing the matching, which means that a value of 0 in any field results in an acceptable match.

Availability
Declared In
OpenTransportProviders.h

OTConnect

Requests a connection to a remote peer. (Deprecated in Mac OS X v10.4.)

OSStatus OTConnect (
   EndpointRef ref,
   TCall *sndCall,
   TCall *rcvCall
);

Parameters
ref
sndCall
rcvCall

This parameter is only meaningful for synchronous calls to the OTConnect function. See TCall data type.

Return Value

A result code. See “Open Transport Result Codes.”

Discussion

If the endpoint is in synchronous mode, the OTConnect function returns after the connection is established and fills in the fields of the TCall structure (referenced by the rcvCall parameter) with the actual values associated with this connection. These might be different from the values you specified using the sndCall parameter.

If the OTConnect function returns with the kOTLookErr result, this might be either because of a pending T_LISTEN or T_DISCONNECT event. That is, either a connection request from another endpoint has interrupted execution of the function, or the remote endpoint has rejected the connection. If you don’t have a notifier installed, you can call the OTLook function to identify the event that caused the kOTLookErr result. If the event is T_LISTEN, you must accept or reject the incoming request and then continue processing the OTConnect function by calling OTRcvConnect. If the event is T_DISCONNECT, you must call the OTRcvDisconnect function to clear the error condition—that is, to deallocate memory and place the endpoint in the correct state.

If the endpoint is in asynchronous mode, the OTConnect function returns before the connection is established with a kOTNoDataErr result to indicate that the connection is in progress. When the connection is established, the endpoint provider calls your notifier, passing T_CONNECT for the code parameter. In response, you must call the OTRcvConnect function to read the connection parameters that would have been returned using the rcvCall parameter if the endpoint were in synchronous mode.

It is possible that the remote address returned in the addr field of the rcvCall parameter is not the same as the address you requested using the sndCall->addr field. This happens when the connection is accepted for a different endpoint than the one receiving the connection request.

Availability
Declared In
OpenTransport.h

OTCountDataBytes

Returns the amount of data currently available to be read. (Deprecated in Mac OS X v10.4.)

OTResult OTCountDataBytes (
   EndpointRef ref,
   OTByteCount *countPtr
);

Parameters
ref
countPtr
Return Value

See the description of the OTResult data type.

Discussion

If the function returns sucessfully, the countPtr parameter points to a buffer containing the amount of data currently available to be read. This does not mean that the buffer contains all the data that was sent. That is, there might be additional data to read after you do the first read.

Availability
Declared In
OpenTransport.h

OTCreateConfiguration

Creates a structure defining a provider’s configuration. (Deprecated in Mac OS X v10.4.)

Modified

OTConfigurationRef OTCreateConfiguration (
   const char *path
);

Parameters
path

A pointer to a character string describing the provider.

Return Value

See the description of the OTConfigurationRef data type.

Discussion

The OTCreateConfiguration function creates a configuration structure that defines the software modules, hardware ports, and options that Open Transport is to use when you call a function to open a provider. This is a private structure, defined by the OTConfiguration data type . To create one, you use the path parameter to pass the OTCreateConfiguration function a string describing the provider service desired.

The simplest possible value of the path parameter is a single protocol module name of the highest-level protocol you want to use; for example, “tcp.” If you do not specify a complete communications path, the Open Transport software uses default settings to construct the rest of the path. For example, if you specify “adsp” for the path parameter, Open Transport defaults to using the AppleTalk DataStream Protocol (ADSP) protocol module layered above the Datagram Delivery Protocol (DDP) protocol module and with LocalTalk on the default port, which is the printer port.

If you want to identify a particular port in the configuration string, you use the port name to do so (described in the section “About Port Information,” beginning on page 6-5). More typically, however, you leave this value blank— for example, using a string with only “adsp” or “adsp, ddp,” which configures the provider with whatever port is specified in the control panel.

To specify more than one protocol module, separate the module names with commas. You can also specify values for options by putting them in parentheses after the protocol name; for example, “adsp, ddp (Checksum=1)” specifies that ADSP is to run on top of DDP and that the checksum option is enabled.

If Open Transport cannot parse the list that you pass in the path parameter, the OTCreateConfiguration function returns ((OTConfiguration*)-1L). If there is insufficient memory to create an OTConfiguration structure, the OTCreateConfiguration function returns NULL.

The OTCreateConfiguration function returns a pointer to the configuration structure it creates. You pass this pointer as a parameter to the open-provider functions such as the OTOpenEndpoint or OTOpenMapper functions.

Availability
Carbon Porting Notes

Passing inline options to OTCreateConfiguration-for example, OTCreateConfiguration("tcp(NoDelay=1)")-is not supported on Mac OS X. Instead, you should explicitly set any options using the function OTOptionManagement.

Declared In
OpenTransport.h

OTCreateDeferredTaskInContext

Creates a reference to a task that can be scheduled to run at deferred task time. (Deprecated in Mac OS X v10.4.)

long OTCreateDeferredTaskInContext (
   OTProcessUPP upp,
   void *arg,
   OTClientContextPtr clientContext
);

Parameters
upp
arg
clientContext
Availability
Declared In
OpenTransport.h

OTCreatePortRef

Creates a port reference that describes a port’s hardware characteristics. (Deprecated in Mac OS X v10.4.)

OTPortRef OTCreatePortRef (
   OTBusType busType,
   OTDeviceType devType,
   OTSlotNumber slot,
   UInt16 other
);

Parameters
busType

The type of bus to which the hardware port is connected; for example, a NuBus or PCI bus. See “The Port Reference” for possible values for this parameter.

devType

The type of hardware device connected to the port, such as LocalTalk or Ethernet. See “The Port Reference”for possible values for this parameter.

slot
other

The port’s multiport identifier—that is, a numeric value that distinguishes between ports when more than one hardware port is connected to a given slot.

Return Value

See the description of the OTPortRef data type.

Discussion

The OTCreatePortRef function creates a port reference structure, which is a 32-bit value that describes a port’s hardware characteristics: its device and bus type, its physical slot number, and, where applicable, its multiport identifier.

Once you have created a port reference, you can use the OTFindPortByRef function to find a specific port with that particular set of characteristics.

To create a port reference, you use the OTCreatePortRef function. You must know all the port’s hardware characteristics: its device and bus type, its slot number, and its multiport identifier (if it has one). You cannot use wildcards to fill in any element you don’t know, although you can use a device type of 0 to allow matches on every kind of device type (following the zero-matches-everything rule). Possible device and bus types are described in the section “The Port Reference.”

To create a port reference for a pseudodevice, use 0 as the value for the bus type, slot number, and multiport identifier, and use the constant kOTPseudoDevice for the device type.

Open Transport has predefined variants of the OTCreatePortRef function for the most commonly used hardware devices, such as the NuBus, PCI, and PCMCIA devices. These three variants are listed here:

#define OTCreateNuBusPortRef(devType, slot, other)\
OTCreatePortRef(kOTNuBus, devType, slot, other)
#define OTCreatePCIPortRef(devType, slot, other)\
OTCreatePortRef(kOTPCIBus, devType, slot, other)
#define OTCreatePCMCIAPortRef(devType, slot, other)\
OTCreatePortRef(kOTPCMCIABus, devType, slot, other)

Once you have identified the port structure you want, you can access the information in its port reference, by using the OTGetDeviceTypeFromPortRef, OTGetBusTypeFromPortRef, and OTGetSlotFromPortRef functions.

Availability
Declared In
OpenTransport.h

OTCreateTimerTaskInContext

Creates a task to be scheduled. (Deprecated in Mac OS X v10.4.)

long OTCreateTimerTaskInContext (
   OTProcessUPP upp,
   void *arg,
   OTClientContextPtr clientContext
);

Parameters
upp
arg
clientContext
Availability
Declared In
OpenTransportProtocol.h

OTDelay

Delays processing for a specified number of seconds. This function is only provided for compatibility with the UNIX sleep function. (Deprecated in Mac OS X v10.4.)

void OTDelay (
   UInt32 seconds
);

Parameters
seconds

The number of seconds to delay.

Discussion

The OTDelay function delays processing for the number of seconds specified in the seconds parameter. While the delay is occurring, OTDelay continuously calls the OTIdle function.

You can only call the OTDelay function from within an application at system task time. This function is only provided for compatibility with the UNIX sleep function to assist with portability of UNIX code.

Availability
Declared In
OpenTransport.h

OTDeleteName

Removes a previously registered entity name. (Deprecated in Mac OS X v10.4.)

OSStatus OTDeleteName (
   MapperRef ref,
   TNetbuf *name
);

Parameters
ref
name
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

If the name-registration protocol defined using the config parameter to the OTOpenMapper or OTAsyncOpenMapper function supports dynamic name and address registration, you can use the OTDeleteName function to delete a registered name.

Availability
Declared In
OpenTransport.h

OTDeleteNameByID

Removes a previously registered name as specified by its name ID. (Deprecated in Mac OS X v10.4.)

OSStatus OTDeleteNameByID (
   MapperRef ref,
   OTNameID nameID
);

Parameters
ref
nameID
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

If the name-registration protocol defined using the config parameter to the OTOpenMapper or OTAsyncOpenMapper function supports dynamic name and address registration, you can use the OTDeleteNameByID function to delete a registered name.

If the mapper is in asynchronous mode, the OTDeleteNameByID function returns immediately. When the function completes execution, the mapper provider calls the notifier function, passing T_DELNAMECOMPLETE for the code parameter, and a pointer to the id parameter in the cookie parameter.

Availability
Declared In
OpenTransport.h

OTDequeue

Removes an element from a list. (Deprecated in Mac OS X v10.4.)

void * OTDequeue (
   void **listHead,
   OTByteCount linkOffset
);

Parameters
listHead
linkOffset
Availability
Declared In
OpenTransport.h

OTDestroyConfiguration

Deletes an OTConfiguration structure. (Deprecated in Mac OS X v10.4.)

void OTDestroyConfiguration (
   OTConfigurationRef cfig
);

Parameters
cfig
Discussion

The OTDestroyConfiguration function deletes the OTConfiguration structure that you specify in the cfig parameter and releases all associated memory.

Availability
Declared In
OpenTransport.h

OTDestroyDeferredTask

Destroys a deferred task created with the OTCreateDeferredTask function. (Deprecated in Mac OS X v10.4.)

OSStatus OTDestroyDeferredTask (
   OTDeferredTaskRef dtCookie
);

Parameters
dtCookie
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

The OTDestroyDeferredTask function makes the dtCookie reference invalid and frees any resources allocated to the task when it was created. You can call this function at any time when you no longer need to schedule the deferred task object. If dtCookie is invalid (a value of 0), the function returns kOTNoError and does nothing.

If you try to destroy a deferred task that is still scheduled, the kEAgainErr error can occur. This is a rare situation that can only happen when you try to destroy the task from within an interrupt service routine or within another deferred task.

Availability
Declared In
OpenTransport.h

OTDestroyTimerTask

Disposes of a timer task. (Deprecated in Mac OS X v10.4.)

void OTDestroyTimerTask (
   OTTimerTask timerTask
);

Parameters
timerTask
Availability
Declared In
OpenTransportProtocol.h

OTDontAckSends

Specifies that a provider copy data before sending it. (Deprecated in Mac OS X v10.4.)

OSStatus OTDontAckSends (
   ProviderRef ref
);

Parameters
ref
Return Value

A result code. See “Open Transport Result Codes.”

Discussion

By default, providers do not acknowledge sends. You need to call the OTDontAckSends function only if you have used the OTAckSends function to turn on send-acknowledgment for a provider.

Availability
Declared In
OpenTransport.h

OTElapsedMicroseconds

Calculates the time elapsed in microseconds since a specified time. (Deprecated in Mac OS X v10.4.)

UInt32 OTElapsedMicroseconds (
   OTTimeStamp *startTime
);

Parameters
startTime
Availability
Declared In
OpenTransport.h

OTElapsedMilliseconds

Calculates the time elapsed in milliseconds since a specified time. (Deprecated in Mac OS X v10.4.)

UInt32 OTElapsedMilliseconds (
   OTTimeStamp *startTime
);

Parameters
startTime
Availability
Declared In
OpenTransport.h

OTEnqueue

Adds an element to a list. (Deprecated in Mac OS X v10.4.)

void OTEnqueue (
   void **listHead,
   void *object,
   OTByteCount linkOffset
);

Parameters
listHead
object
linkOffset
Availability
Declared In
OpenTransport.h

OTEnterNotifier

Limits the notifications that can be sent to your notifier. (Deprecated in Mac OS X v10.4.)

Boolean OTEnterNotifier (
   ProviderRef ref
);

Parameters
ref
Availability
Declared In
OpenTransport.h

OTExtractNBPName

Extracts the name part of an NBP name from an NBP entity structure. (Deprecated in Mac OS X v10.4.)

void OTExtractNBPName (
   const NBPEntity *entity,
   char *name
);

Parameters
entity
name

A pointer to the string buffer in which to store the name portion of an NBP name string that you wish to extract from the NBP entity.

Discussion

The OTExtractNBPName function extracts the name part of an NBP name from the specified NBP entity structure and stores it into the string buffer specified by the name parameter. This function inserts a backslash (\) in front of any backslash, colon (:), or at-sign (@) it finds in an NBP name so that mapper functions can use a correctly formatted NBP name.

Availability
Declared In
OpenTransportProviders.h

OTExtractNBPType

Extracts the type part of an NBP name from an NBP entity structure. (Deprecated in Mac OS X v10.4.)

void OTExtractNBPType (
   const NBPEntity *entity,
   char *typeVal
);

Parameters
entity
typeVal

A pointer to the string buffer in which to store the type portion of an NBP name string that you wish to extract from the NBP entity.

Discussion

The OTExtractNBPType function extracts the type part of an NBP name from the specified NBP entity structure and stores it into the string buffer specified by the type parameter. This function inserts a backslash (\) in front of any backslash, colon (:), or at-sign (@) it finds in an NBP name so that mapper functions can use a correctly formatted NBP name.

Availability
Declared In
OpenTransportProviders.h

OTExtractNBPZone

Extracts the zone part of an NBP name from an NBP entity structure. (Deprecated in Mac OS X v10.4.)

void OTExtractNBPZone (
   const NBPEntity *entity,
   char *zone
);

Parameters
entity
zone

A pointer to the string buffer in which to store the type portion of an NBP name string that you wish to extract from the NBP entity.

Discussion

The OTExtractNBPZone function extracts the zone part of an NBP name from the specified NBP entity structure and stores it into the string buffer specified by the zone parameter. This function inserts a backslash (\) in front of any backslash, colon (:), or at-sign (@) it finds in an NBP name so that mapper functions can use a correctly formatted NBP name.

Availability
Declared In
OpenTransportProviders.h

OTFindAndRemoveLink

Finds a link in a FIFO list and removes it. (Deprecated in Mac OS X v10.4.)

OTLink * OTFindAndRemoveLink (
   OTList *list,
   OTListSearchUPP proc,
   const void *ref
);

Parameters
list
proc
ref
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTFindLink

Finds a link in a FIFO list and returns a pointer to it. (Deprecated in Mac OS X v10.4.)

OTLink * OTFindLink (
   OTList *list,
   OTListSearchUPP proc,
   const void *ref
);

Parameters
list
proc
ref
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTFindOption

Finds a specific option in an options buffer. (Deprecated in Mac OS X v10.4.)

TOption * OTFindOption (
   UInt8 *buffer,
   UInt32 buflen,