ADC Home > Reference Library > Reference > Carbon > Networking > Open Transport Reference >

< 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,
   OTXTILevel level,
   OTXTIName name
);

Parameters
buffer

A pointer to the buffer containing the option to be found.

buflen

The size of the buffer containing the option to be found.

level
name
Return Value

See the description of the TOption data type.

Discussion

Given a buffer such as might be returned by the OTOptionManagement function or by any endpoint function that returns a buffer containing option information, you can use the OTFindOption function to find a specific option in the buffer.

Availability
Declared In
OpenTransport.h

OTFindPort

Obtains information about a port that corresponds to a given port name. (Deprecated in Mac OS X v10.4.)

Boolean OTFindPort (
   OTPortRecord *portRecord,
   const char *portName
);

Parameters
portName

A pointer to a port structure that contains information about the port you specified with the portName parameter.

portName

The name of the port about which you want information.

Discussion

The OTFindPort function returns information about a port that corresponds to a given port name. Each port in a system has a unique port name, which you can obtain through a previous call or set of calls to the OTGetIndexedPort function.

You must allocate the port structure; the function fills this structure with information about the port indicated by the portName parameter. If the function returns false, the contents of the structure are not significant.

Availability
Declared In
OpenTransport.h

OTFindPortByRef

Obtains information about a port that corresponds to its given port reference. (Deprecated in Mac OS X v10.4.)

Boolean OTFindPortByRef (
   OTPortRecord *portRecord,
   OTPortRef ref
);

Parameters
portRecord
ref
Discussion

The OTFindPortByRef function returns information about a port identified by its port reference. A port reference is a 32-bit value that describes a port’s hardware characteristics: its bus and device type, its physical slot number, and, where applicable, its multiport identifier. This identifier differentiates between multiple hardware ports on a given slot.

You must allocate the port structure; the function fills this structure with information about the port indicated by the ref parameter. If the function returns false, the contents of the structure are not significant.

Availability
Declared In
OpenTransport.h

OTFree

Frees memory allocated using the OTAlloc function. (Deprecated in Mac OS X v10.4.)

OTResult OTFree (
   void *ptr,
   OTStructType structType
);

Parameters
ptr

A pointer to the structure to be deallocated. This is the pointer returned by the OTAlloc function.

structType
Return Value

See the description of the OTResult data type.

Discussion

In order to use the OTFree function, you must not have changed the memory allocated by the OTAlloc function for the structure specified by the structType parameter or for any of the buffers to which it points.

You are responsible for passing a structType parameter that exactly matches the type of structure being freed.

The OTFree function, along with the OTAlloc function, is provided mainly forcompatibility with XTI.

Availability
Declared In
OpenTransport.h

OTFreeMem

Frees memory allocated with the OTAllocMem function. (Deprecated in Mac OS X v10.4.)

void OTFreeMem (
   void *mem
);

Parameters
mem
Availability
Declared In
OpenTransport.h

OTGetBusTypeFromPortRef

Extracts the value of the bus type from a port reference. (Deprecated in Mac OS X v10.4.)

UInt16 OTGetBusTypeFromPortRef (
   OTPortRef ref
);

Parameters
ref
Discussion

The OTGetBusTypeFromPortRef function extracts the bus type value from a port reference with unknown hardware values. You can obtain such a port reference when another application passes one to you or when you use the OTGetIndexedPort function to access a port structure into which another application has put its own port reference.

Availability
Declared In
OpenTransport.h

OTGetClockTimeInSecs

Returns the number of seconds that have elapsed since system boot time. (Deprecated in Mac OS X v10.4.)

UInt32 OTGetClockTimeInSecs (
   void
);

Parameters
Availability
Declared In
OpenTransport.h

OTGetDeviceTypeFromPortRef

Extracts the value of the hardware device type from a port reference. (Deprecated in Mac OS X v10.4.)

OTDeviceType OTGetDeviceTypeFromPortRef (
   OTPortRef ref
);

Parameters
ref
Return Value

See the description of the OTDeviceType data type.

Discussion

The OTGetDeviceTypeFromPortRef function extracts the device type value from a port reference with unknown hardware values. You can obtain such a port reference when another application passes one to you or when you use the OTGetIndexedPort function to access a port structure into which another application has put its own port reference.

Availability
Declared In
OpenTransport.h

OTGetEndpointInfo

Obtains information about an endpoint that has been opened. (Deprecated in Mac OS X v10.4.)

OSStatus OTGetEndpointInfo (
   EndpointRef ref,
   TEndpointInfo *info
);

Parameters
ref
info
Return Value

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

Discussion

The OTGetEndpointInfo function returns information about

Availability
Declared In
OpenTransport.h

OTGetEndpointState

Obtains the current state of an endpoint. (Deprecated in Mac OS X v10.4.)

OTResult OTGetEndpointState (
   EndpointRef ref
);

Parameters
ref
Return Value

See the description of the OTResult data type.

Discussion

The OTGetEndpointState function returns an integer greater than or equal to 0 indicating the state of the specified endpoint. The endpoint state enumeration describes possible endpoint states and lists their decimal value.

If the function fails, it returns a negative integer specifying the error code. You must open an endpoint before you can determine its state.

You might need to know an endpoint’s state in order to determine whether a function has completed or whether the endpoint is in an appropriate state for the function that you want to call next.

This function returns endpoint state information immediately, whether the endpoint is in synchronous or asynchronous mode.

Availability
Declared In
OpenTransport.h

OTGetFirst

Returns a pointer to the first element in a FIFO list. (Deprecated in Mac OS X v10.4.)

OTLink * OTGetFirst (
   OTList *list
);

Parameters
list
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTGetIndexedLink

Returns a pointer to the link at a specified position in a FIFO list. (Deprecated in Mac OS X v10.4.)

OTLink * OTGetIndexedLink (
   OTList *list,
   OTItemCount index
);

Parameters
list
index
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTGetIndexedPort

Iterates through the ports available on your computer. (Deprecated in Mac OS X v10.4.)

Boolean OTGetIndexedPort (
   OTPortRecord *portRecord,
   OTItemCount index
);

Parameters
portRecord
index
Discussion

The OTGetIndexedPort function returns information about the ports available on your local system. To iterate through all the ports on your computer, call the function repeatedly, incrementing the index parameter each time (starting with 0) until the function returns false. Each time the function returns true, it fills in the port structure that you provide with information about a specific port. You can use this information, for example, when specifying a provider configuration string for the OTCreateConfiguration function.

You must allocate the port structure; the function fills this structure with information about the port indicated by the index parameter. If the function returns false, the contents of the structure are not significant.

Availability
Declared In
OpenTransport.h

OTGetLast

Returns the last element in a FIFO list. (Deprecated in Mac OS X v10.4.)

OTLink * OTGetLast (
   OTList *list
);

Parameters
list
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTGetNBPEntityLengthAsAddress

Obtains the size of an NBP entity structure. (Deprecated in Mac OS X v10.4.)

OTByteCount OTGetNBPEntityLengthAsAddress (
   const NBPEntity *entity
);

Parameters
entity
Return Value

See the description of the OTByteCount data type.

Discussion

The OTGetNBPEntityLengthAsAddress function obtains the number of bytes needed to store an NBP entity structure into an NBP or combined DDP-NBP address structure.

Availability
Declared In
OpenTransportProviders.h

OTGetProtAddress

Obtains the address to which an endpoint is bound and, if the endpoint is currently connected, obtains the address of its peer. (Deprecated in Mac OS X v10.4.)

OSStatus OTGetProtAddress (
   EndpointRef ref,
   TBind *boundAddr,
   TBind *peerAddr
);

Parameters
ref
boundAddr

If you are calling this function only to determine the address of the peer endpoint, you can set the boundAddr parameter to NIL.

The boundAddr->qlen field is ignored. See EndpointRef data type.

peerAddr
Return Value

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

Discussion

The OTGetProtAddress function returns the address to which an endpoint is bound in the boundAddr parameter and, if the endpoint is currently connected, the address of its peer in the peerAddr parameter. Not all endpoints support this function. A value of T_XPG4_1 in the flags field of the TEndpointInfo structure indicates that the endpoint does support this function.

You are responsible for initializing the buffers required to hold the local and peer addresses. The addr field of the TEndpointInfo structure specifies the maximum amount of memory needed to store the address of an endpoint. Use this value to set the size of the buffers.

The information returned by the OTGetProtAddress function is affected by the state of the endpoint specified by the ref parameter. If the endpoint is in the T_UNBND state, the boundAddr->addr.len field is set to 0. If the endpoint is not in the T_DATAXFER state, the peerAddr->addr.len field is set to 0.

If the endpoint is in asynchronous mode and a notifier is not installed, it is not possible to determine when the function completes.

Availability
Declared In
OpenTransport.h

OTGetSlotFromPortRef

Extracts slot information from a port reference. (Deprecated in Mac OS X v10.4.)

OTSlotNumber OTGetSlotFromPortRef (
   OTPortRef ref,
   UInt16 *other
);

Parameters
ref
other

A pointer to a 16-bit buffer you provide into which the function places a value that distinguishes between ports when more than one hardware port is connected to a given slot. Specify NULL for this parameter if you do not want the function to return this information.

Return Value

See the description of the OTSlotNumber data type.

Discussion

The OTGetSlotFromPortRef function extracts slot information from a port reference with unknown hardware values. You can obtain such a port reference when another application passes one to you or when you use the OTGetIndexedPort function to access a port structure into which another application has put its own port reference.

Note that the slot numbers are physical; that is, they are the slot numbers returned by the Slot Manager and not the slots seen in various network configuration applications. Physical slot numbers depend on the type of card installed. For example, NuBus cards number their slots 9–13, which appear in the AppleTalk or TCP control panels as slots 1–5.

Availability
Declared In
OpenTransport.h

OTGetTimeStamp

Obtains the current timestamp. (Deprecated in Mac OS X v10.4.)

void OTGetTimeStamp (
   OTTimeStamp *currentTime
);

Parameters
currentTime
Availability
Declared In
OpenTransport.h

OTIdle

Idles your computer. (Deprecated in Mac OS X v10.4.)

void OTIdle (
   void
);

Discussion

You can call the OTIdle function while you are waiting for asynchronous provider operations to complete. It is not necessary for the correct operation of Open Transport to call this function, but it provides compatibility for existing programs that use an idling function.

Availability
Declared In
OpenTransport.h

OTInetAddressToName

Determines the canonical domain name of the host associated with an internet address. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetAddressToName (
   InetSvcRef ref,
   InetHost addr,
   InetDomainName name
);

Parameters
ref
addr
name
Return Value

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

Discussion

If you call this function asynchronously, the TCP/IP service provider calls your notifier function with the T_DNRADDRTONAMECOMPLETE completion event code when the function completes. The cookie parameter to the notifier function contains a pointer to the InetHost structure you specified in the addr parameter. If you had more than one simultaneous outstanding call to the OTInetAddressToName function, you can use this information to determine which call has completed execution.

Availability
Declared In
OpenTransportProviders.h

OTInetGetInterfaceInfo

Returns internet address information about the local host. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetGetInterfaceInfo (
   InetInterfaceInfo *info,
   SInt32 val
);

Parameters
info
val

An index into the local host’s array of configured IP interfaces. Specify 0 for information about the first interface. Specify kDefaultInetInterface to get information about the primary interface.

Return Value

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

Discussion

Because the architecture of Open Transport TCP/IP provides for multihoming, in principle a given host can receive packets simultaneously through more than one network interface. For each IP interface configured for the local host, the OTInetGetInterfaceInfo function provides the internet address and subnet mask, a default gateway (that is, a gateway, if any exists, that can be used to route any packet to all destinations outside the locally connected subnet), and a domain name server, if any is known. The function also returns the version number of the OTInetGetInterfaceInfo function and, if available, the broadcast address for each interface. If the broadcast address is not available, you can determine it from the internet address and subnet mask.

Because multihoming has not been implemented in the initial release of Open Transport, the OTInetGetInterfaceInfo function never returns information for more than one interface.

Availability
Declared In
OpenTransportProviders.h

OTInetGetSecondaryAddresses

Returns the active secondary IP addresses. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetGetSecondaryAddresses (
   InetHost *addr,
   UInt32 *count,
   SInt32 val
);

Parameters
addr
count
val
Return Value

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

Availability
Declared In
OpenTransportProviders.h

OTInetHostToString

Converts an an address in InetHost format into a character string in dotted-decimal notation. (Deprecated in Mac OS X v10.4.)

void OTInetHostToString (
   InetHost host,
   char *str
);

Parameters
host
str

A pointer to a C string containing an IP address in dotteddecimal notation (for example, “12.13.14.15”). You must allocate storage for this string and provide the pointer to the function.

Availability
Declared In
OpenTransportProviders.h

OTInetMailExchange

Returns mail-exchange-host names and preference information for a domain name you specify. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetMailExchange (
   InetSvcRef ref,
   char *name,
   UInt16 *num,
   InetMailExchange *mx
);

Parameters
ref
name

A pointer to a host name, partially qualified domain name, or fully qualified domain name for which you want mail exchange information.

num

A pointer to the number of elements in the array pointed to by the mx parameter. When the function completes, it sets the number pointed to by the num parameter to the actual number of elements filled in.

mx
Return Value

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

Discussion

In order to deliver mail, a mail application must determine the fully qualified domain name of the host to which the mail should be sent. That host might be the final destination of the mail, a mail server, or a router. The domain name system servers maintain mail-exchange resource records that pair domain names with the hosts that can accept mail for that domain. Each domain name can be paired with any number of host names; each record containing such a pair also contains a preference number. The mailer sends the mail to the host with the lowest preference number first and tries the others in turn until the mail is delivered or until the mailer decides that the mail is undeliverable.

The OTInetMailExchange function returns mail-exchange-host and preference information for the domain name you specify. You must then determine the address of the host and how best to deliver the mail. You can specify as many elements to the array of InetMailExchange structures as you wish.

If you call this function asynchronously, the TCP/IP service provider calls your notifier function with the T_DNRMAILEXCHANGECOMPLETE completion event code when the function completes. The cookie parameter to the notifier function contains the array pointer you specified in the mx parameter. If you had more than one simultaneous outstanding call to the OTInetMailExchange function, you can use this information to determine which call has completed execution.

Availability
Declared In
OpenTransportProviders.h

OTInetQuery

Executes a generic DNS query. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetQuery (
   InetSvcRef ref,
   char *name,
   UInt16 qClass,
   UInt16 qType,
   char *buf,
   OTByteCount buflen,
   void **argv,
   OTByteCount argvlen,
   OTFlags flags
);

Parameters
ref
name
qClass
qType
buf
buflen
argv
argvlen
flags
Return Value

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

Availability
Declared In
OpenTransportProviders.h

OTInetStringToAddress

Resolves a domain name to its equivalent internet addresses. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetStringToAddress (
   InetSvcRef ref,
   char *name,
   InetHostInfo *hinfo
);

Parameters
ref
name

A pointer to the domain name you want to resolve. This can be a host name, a partially qualified domain name, a fully qualified domain name, or an internet address in dotted-decimal format.

hinfo
Return Value

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

Discussion

Because the architecture of Open Transport TCP/IP provides for multihoming, a single host can be associated with multiple internet addresses. You can use the OTInetStringToAddress function to return multiple addresses for multihomed hosts.

Because multihoming has not been implemented in the initial release of Open Transport, the OTInetStringToAddress function never returns more than one address.

If you specify an internet address in dotted-decimal format for the hinfo parameter, the OTInetStringToAddress function places that address in the InetHostInfo.name field instead of a canonical domain name.

If you call the OTInetStringToAddress function asynchronously, the TCP/IP service provider calls your notifier function with the T_DNRSTRINGTOADDRCOMPLETE completion event code when the function completes. The cookie parameter to the notifier function contains the pointer you specified in the hinfo parameter. If you had more than one simultaneous outstanding call to the OTInetStringToAddress function, you can use this information to determine which call has completed execution.

Availability
Declared In
OpenTransportProviders.h

OTInetStringToHost

Converts an IP address string from dotted-decimal notation or hexadecimal notation to an InetHost data type. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetStringToHost (
   const char *str,
   InetHost *host
);

Parameters
str

A pointer to a character string containing an IP address in either dotted-decimal notation (for example, “12.13.14.15”) or hexadecimal notation (for example, “0x0c0d0e0f”).

host
Return Value

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

Availability
Declared In
OpenTransportProviders.h

OTInetSysInfo

Returns details about a host’s processor and operating system. (Deprecated in Mac OS X v10.4.)

OSStatus OTInetSysInfo (
   InetSvcRef ref,
   char *name,
   InetSysInfo *sysinfo
);

Parameters
ref
name

The name of the host about which you want information. This can be a host name (including the local host), a partially qualified domain name, or a fully qualified domain name.

sysinfo
Return Value

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

Discussion

The information returned by this function is maintained by the domain name server. If you call this function asynchronously, the TCP/IP service provider calls your notifier function with the T_DNRSYSINFOCOMPLETE completion event code when the function completes. The cookie parameter to the notifier function contains a pointer to the InetSysInfo structure you specified in the sysinfo parameter. If you had more than one simultaneous outstanding call to the OTInetSysInfo function, you can use this information to determine which call has completed execution.

Availability
Declared In
OpenTransportProviders.h

OTInitDDPAddress

Initializes a DDP address structure. (Deprecated in Mac OS X v10.4.)

void OTInitDDPAddress (
   DDPAddress *addr,
   UInt16 net,
   UInt8 node,
   UInt8 socket,
   UInt8 ddpType
);

Parameters
addr
net

The network number you wish to specify. Set to 0 to default to the local network.

node

The node ID you wish to specify. Set to 0 to default to the local node.

socket

The socket number you wish to specify. Set to 0 to allow Open Transport to assign a socket dynamically when you use this address to bind an endpoint.

ddpType

The DDP type you wish to specify. Set to 0 unless you are using DDP.

Availability
Declared In
OpenTransportProviders.h

OTInitDDPNBPAddress

Initializes a combined DDP-NBP address structure. (Deprecated in Mac OS X v10.4.)

OTByteCount OTInitDDPNBPAddress (
   DDPNBPAddress *addr,
   const char *name,
   UInt16 net,
   UInt8 node,
   UInt8 socket,
   UInt8 ddpType
);

Parameters
addr
name

A pointer to the NBP string you wish to use for the NBP name.

net

The network number you wish to specify. Set to 0 to default to the local network.

node

The node ID you wish to specify. Set to 0 to default to the local node.

socket

The socket number you wish to specify. Set to 0 to allow Open Transport to assign a socket dynamically when you use this address to bind an endpoint.

ddpType

The DDP type you wish to specify. Set to 0 unless you are using DDP.

Return Value

See the description of the OTByteCount data type.

Discussion

The OTInitDDPNBPAddress function initializes a combined DDP-NBP address structure with the data provided in the parameters: NBP name, network number, node ID, socket number, and DDP type. The function returns the total size of the address structure, which is the length of the name parameter plus the size of a DDPAddress structure.

Availability
Declared In
OpenTransportProviders.h

OTInitDNSAddress

Fills in a DNSAddress structure with the data you provide. (Deprecated in Mac OS X v10.4.)

OTByteCount OTInitDNSAddress (
   DNSAddress *addr,
   char *str
);

Parameters
addr
str

A pointer to a domain name string. This string can be just a host name (otteam), a partially qualified domain name (for example, “otteam.ssw”), a fully qualified domain name (for example, “otteam.ssw.apple.com.”), or an internet address in dotteddecimal format (for example, “17.202.99.99”), and can optionally include the port number (for example, “otteam.ssw.apple.com:25” or “17.202.99.99:25”).

Return Value

See the description of the OTByteCount data type.

Discussion

This function fills in the fAddressType field of the DNSAddress structure with the value AF_DNS, fills in the fName field with the address string you specify, and returns the size of the resulting DNSAddress structure as an unsigned integer. You can use the DNSAddress structure to provide an address when you use a UDP or TCP endpoint. If you do so, the domain name resolver resolves the address for you automatically.

Availability
Declared In
OpenTransportProviders.h

OTInitInetAddress

Fills in an InetAddress structure with the data you provide. (Deprecated in Mac OS X v10.4.)

void OTInitInetAddress (
   InetAddress *addr,
   InetPort port,
   InetHost host
);

Parameters
addr
port
host
Discussion

This function fills in the fAddressType field of the InetAddress structure with the value AF_INET. You use the InetAddress structure when providing a TCP or UDP address to the Open Transport functions OTConnect, OTSndURequest, and OTBind. You are not required to use the OTInitInetAddress function when creating an InetAddress structure; this function is provided for your convenience only.

Availability
Declared In
OpenTransportProviders.h

OTInitNBPAddress

Initializes an NBP address structure. (Deprecated in Mac OS X v10.4.)

OTByteCount OTInitNBPAddress (
   NBPAddress *addr,
   const char *name
);

Parameters
addr
name

A pointer to the NBP string you wish to use for the NBP name.

Return Value

See the description of the OTByteCount data type.

Discussion

The OTInitNBPAddress function can be used to initialize an NBP address structure with the NBP name specified in the name parameter, which is assumed to already be in the correct string format. The function returns the size of the NBP address structure, which is the size of the fAddressType field plus the length of the string in the name parameter.

Availability
Declared In
OpenTransportProviders.h

OTInitNBPEntity

Initializes an NBP entity structure. (Deprecated in Mac OS X v10.4.)

void OTInitNBPEntity (
   NBPEntity *entity
);

Parameters
entity
Discussion

The OTInitNBPEntity function initializes an NBP entity structure, setting the name, type and zone parts of an NBP name to empty strings.

Availability
Declared In
OpenTransportProviders.h

OTInstallNotifier

Installs a notifier function. (Deprecated in Mac OS X v10.4.)

OSStatus OTInstallNotifier (
   ProviderRef ref,
   OTNotifyUPP proc,
   void *contextPtr
);

Parameters
ref
proc

For C++ applications, the proc parameter must point to either a C function or a static member function. See OTNotifyUPP data type.

contextPtr

A context pointer for your use. The provider passes this value unchanged to your notifier function when it calls the function.

Return Value

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

Discussion

The OTInstallNotifier function installs a notifier function for the provider that you specify. Changing a provider’s mode of execution does not affect the notifier function. The notifier function remains installed until you remove it using the OTRemoveNotifier function or until you close the provider.

Before calling the OTInstallNotifier function, you must open the provider for which you want to install the notifier. If you open a provider asynchronously (for example, with the OTAsyncOpenEndpoint function), you must pass a pointer to a notifier function as a parameter to the function used to open the provider. In this case, you don’t need to call the OTInstallNotifier function unless you want to install a different notifier function. If you do, you must call the OTRemoveNotifier function before calling the OTInstallNotifier function.

Opening a provider synchronously (for example, with the OTOpenEndpoint function) opens the provider but does not install a notifier function for it. If you need a notifier function for a provider opened synchronously, you must call the OTInstallNotifier function. This notifier would not return completion events, but would return asynchronous events advising you of the arrival of data, of changes in flow-control restrictions, and so on.

Call the OTInstallNotifier function only when no provider functions are executing for the provider that you specify. Otherwise, the OTInstallNotifier function returns the result code kOTStateChangeErr.

Availability
Declared In
OpenTransport.h

OTIoctl

Sends a module-specific command to an Open Transport protocol module. (Deprecated in Mac OS X v10.4.)

SInt32 OTIoctl (
   ProviderRef ref,
   UInt32 cmd,
   void *data
);

Parameters
ref
cmd

A routine selector for the module-specific command.

data

Data to be used by the module-specific command, or a pointer to such data. The interpretation of the data parameter is command specific.

Discussion

The OTIoctl function sends a module-specific command to an Open Transport protocol module. The OTIoctl function runs synchronously or asynchronously, matching the provider’s mode of execution.

If the OTIoctl function completes synchronously without error, it returns 0 or a positive integer. The positive integer’s meaning is command specific. If the OTIoctl function fails while executing synchronously, its return value is a negative integer corresponding to an Open Transport result code.

If the OTIoctl function runs asynchronously, it returns immediately with a return value kOTNoError or another Open Transport result code. When the function completes execution, Open Transport calls the notifier function you specify, passing the event code kStreamIoctlEvent and a result parameter indicating the result of the completed OTIoctl function. If the value of the result parameter is greater than 0, the corresponding result code is defined by the command; otherwise, the value of the result parameter corresponds to an Open Transport result code.

Availability
Declared In
OpenTransport.h

OTIsAckingSends

Determines whether a provider is acknowledging sends. (Deprecated in Mac OS X v10.4.)

Boolean OTIsAckingSends (
   ProviderRef ref
);

Parameters
ref
Discussion

The OTIsAckingSends function returns true if the provider acknowledges sends and false if it does not.

Availability
Declared In
OpenTransport.h

OTIsBlocking

Returns a boolean indicating whether a provider is blocking. (Deprecated in Mac OS X v10.4.)

Boolean OTIsBlocking (
   ProviderRef ref
);

Parameters
ref
Availability
Declared In
OpenTransport.h

OTIsInList

Determines whether the specified link is in the specified list. (Deprecated in Mac OS X v10.4.)

Boolean OTIsInList (
   OTList *list,
   OTLink *link
);

Parameters
list
link
Availability
Declared In
OpenTransport.h

OTIsSynchronous

Returns a provider’s current mode of execution. (Deprecated in Mac OS X v10.4.)

Boolean OTIsSynchronous (
   ProviderRef ref
);

Parameters
ref
Discussion

The OTIsSynchronous function returns true if a provider is in synchronous mode or returns false if the provider is in asynchronous mode.

Availability
Declared In
OpenTransport.h

OTLeaveNotifier

Allows Open Transport to resume sending primary and completion events. (Deprecated in Mac OS X v10.4.)

void OTLeaveNotifier (
   ProviderRef ref
);

Parameters
ref
Availability
Declared In
OpenTransport.h

OTLIFODequeue

Removes the first link in a LIFO list and returns a pointer to it. (Deprecated in Mac OS X v10.4.)

OTLink * OTLIFODequeue (
   OTLIFO *list
);

Parameters
list
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTLIFOEnqueue

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

void OTLIFOEnqueue (
   OTLIFO *list,
   OTLink *link
);

Parameters
list
link
Availability
Declared In
OpenTransport.h

OTLIFOStealList

Removes all links in a LIFO list and returns a pointer to the first link in the list. (Deprecated in Mac OS X v10.4.)

OTLink * OTLIFOStealList (
   OTLIFO *list
);

Parameters
list
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTListen

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

OSStatus OTListen (
   EndpointRef ref,
   TCall *call
);

Parameters
ref
call
Return Value

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

Discussion

You use the OTListen function to listen for incoming connection requests. On return, the function fills in the TCall structure referenced by the call parameter with information about the connection request. After retrieving the connection request using the OTListen function, you can reject the request using the OTSndDisconnect function, or you can accept the request using the OTAccept function.

If the endpoint is in synchronous mode and is blocking, the OTListen function returns when a connection request has arrived. If the endpoint is in asynchronous mode or is not blocking, the OTListen function returns any pending connection requests or returns the kOTNoDataErr result if there are no pending connection requests. You can also call the OTListen function from within a notifier function in response to the T_LISTEN event. In this case, the function returns a result immediately.

Availability
Declared In
OpenTransport.h

OTLook

Determines the current asynchronous event pending for an endpoint. (Deprecated in Mac OS X v10.4.)

OTResult OTLook (
   EndpointRef ref
);

Parameters
ref
Return Value

See the description of the OTResult data type.

Discussion

You use the OTLook function in one of two cases. First, if the endpoint is in synchronous mode, you can call the OTLook function to poll for incoming data or connection requests. Second, certain asynchronous events might cause a synchronous function to fail with the result kOTLookErr. For example, if you call OTAccept and the endpoint gets a T_DISCONNECT event, the OTAccept function returns with kOTLookErr. In this case, you need to call the OTLook function to determine what event caused the original function to fail. Table 3-7 on page 3-26 lists the functions that might return the kOTLookErr result and the events that can cause these functions to fail.

The OTLook function returns an integer value that specifies the asynchronous event pending for the endpoint specified by the ref parameter. On error, OTLook returns a negative integer corresponding to a result code.

If there are multiple events pending, the OTLook function first looks for one ofthe following events: T_LISTEN, T_CONNECT, T_DISCONNECT, T_UDERR, or T_ORDREL. If it finds more than one of these, it returns them to you in first-in, first-out order. After processing these events, the OTLook function looks for the T_DATA, T_REQUEST, and T_REPLY events. If it finds more than one of these, it returns them to you in first-in, first-out order. You cannot use the OTLook function to poll for completion events.

Unless you are operating exclusively in synchronous mode, it is recommended that you use notifier functions to get information about pending events for an endpoint.

Availability
Declared In
OpenTransport.h

OTLookupName

Finds and returns all addresses that correspond to a particular name or name pattern, or confirms that a name is registered. (Deprecated in Mac OS X v10.4.)

OSStatus OTLookupName (
   MapperRef ref,
   TLookupRequest *req,
   TLookupReply *reply
);

Parameters
ref
req
reply
Return Value

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

Discussion

You can use the OTLookupName function to find out whether a name is registered and what address is associated with that name. You use the req parameter to supply the information needed for the search: what name should be looked up and, optionally, what node contains that information, how many matches you expect to find, and how long the search should continue before the function returns. On return, the reply parameter contains the names field that points to the buffer where the matching entries are stored and the rspcount field that specifies the number of matching entries.

For each registered name found, the OTLookupName function stores the following information in the buffer referenced by the names field of the reply parameter:

unsigned short addrLen; /* length of address that follows*/
unsigned short nameLen; /* length of name that follows */
unsigned char addr[]; /* address */
unsigned char name[]; /* name, padded to quad-word boundary*/

If you are searching for names using a name pattern and you expect that more than one name will be returned to you, you need to parse the reply buffer to extract the matching names.

If you call the OTLookupName function asynchronously, the mapper provider calls your notifier function passing one of two completion codes for the code parameter (T_LKUPNAMERESULT or T_LKUPNAMECOMPLETE) and passing the reply parameter in the cookie parameter. The mapper provider passes the T_LKUPNAMERESULT code each time it stores a name in the reply buffer, and it passes the T_LKUPNAMECOMPLETE code when it is done. When you receive this event, examine the rspcount field to determine whether there is a last name to retrieve from the reply buffer. The use of both codes is a feature that gives you a choice about how to process multiple names when searching for names matching a pattern.

The cookie parameter to the notifier contains the reply parameter.

The format of the names and protocol addresses are specific to the underlying protocol. Consult the documentation supplied for your protocol for more information.

Availability
Declared In
OpenTransport.h

OTMemcmp

Compares the contents of two memory locations. (Deprecated in Mac OS X v10.4.)

Boolean OTMemcmp (
   const void *mem1,
   const void *mem2,
   OTByteCount nBytes
);

Parameters
mem1
mem2
nBytes
Availability
Declared In
OpenTransport.h

OTMemcpy

Copies data from one memory location to another; the source and destination locations must not overlap. (Deprecated in Mac OS X v10.4.)

void OTMemcpy (
   void *dest,
   const void *src,
   OTByteCount nBytes
);

Parameters
dest
src
nBytes
Availability
Declared In
OpenTransport.h

OTMemmove

Copies data from one memory location to another; the source and destination locations may overlap. (Deprecated in Mac OS X v10.4.)

void OTMemmove (
   void *dest,
   const void *src,
   OTByteCount nBytes
);

Parameters
dest
src
nBytes
Availability
Declared In
OpenTransport.h

OTMemset

Sets the specified memory range to a specific value. (Deprecated in Mac OS X v10.4.)

void OTMemset (
   void *dest,
   OTUInt8Param toSet,
   OTByteCount nBytes
);

Parameters
dest
toSet
nBytes
Availability
Declared In
OpenTransport.h

OTMemzero

Initializes the specified memory range to 0. (Deprecated in Mac OS X v10.4.)

void OTMemzero (
   void *dest,
   OTByteCount nBytes
);

Parameters
dest
nBytes
Availability
Declared In
OpenTransport.h

OTNextOption

Locates the next TOption structure in a buffer. (Deprecated in Mac OS X v10.4.)

OSStatus OTNextOption (
   UInt8 *buffer,
   UInt32 buflen,
   TOption **prevOptPtr
);

Parameters
buffer

A pointer to the buffer containing the option to be found.

buflen

A long specifying the size of the buffer containing the option to be found.

prevOptPtr
Return Value

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

Discussion

The OTNextOption function allows you to parse through a buffer containing TOption structures describing an endpoint’s option values. Within the buffer, TOption structures are aligned to long-word boundaries. This function takes into account this padding when it calculates the beginning address of the next TOption structure and it returns that address in the prevOptPtr parameter.

The first time you call the option, set the prevOptPtr parameter to the beginning address of the buffer. When the function returns, the prevOptPtr parameter points to the next (second) option in the buffer. You can continue this process, specifying the value returned for the prevOptPtr parameter by the previous invocation of the function, each time you call the function to obtain the beginning address of each option in the buffer.

Availability
Declared In
OpenTransport.h

OTOpenAppleTalkServicesInContext

Opens a synchronous AppleTalk service provider. (Deprecated in Mac OS X v10.4.)

ATSvcRef OTOpenAppleTalkServicesInContext (
   OTConfigurationRef cfig,
   OTOpenFlags flags,
   OSStatus *err,
   OTClientContextPtr clientContext
);

Parameters
cfig
flags
err
clientContext
Return Value

See the description of the ATSvcRef data type.

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

OTOpenEndpointInContext

Opens an endpoint that operates synchronously. (Deprecated in Mac OS X v10.4.)

EndpointRef OTOpenEndpointInContext (
   OTConfigurationRef config,
   OTOpenFlags oflag,
   TEndpointInfo *info,
   OSStatus *err,
   OTClientContextPtr clientContext
);

Parameters
config
oflag
info
err
clientContext
Return Value

See the description of the EndpointRef data type.

Availability
Declared In
OpenTransport.h

OTOpenInternetServicesInContext

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

InetSvcRef OTOpenInternetServicesInContext (
   OTConfigurationRef cfig,
   OTOpenFlags oflag,
   OSStatus *err,
   OTClientContextPtr clientContext
);

Parameters
cfig
oflag
err
clientContext
Return Value

See the description of the InetSvcRef data type.

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

OTOpenMapperInContext

Creates a synchronous mapper provider and returns a mapper reference. (Deprecated in Mac OS X v10.4.)

MapperRef OTOpenMapperInContext (
   OTConfigurationRef config,
   OTOpenFlags oflag,
   OSStatus *err,
   OTClientContextPtr clientContext
);

Parameters
config
oflag
err
clientContext
Return Value

See the description of the MapperRef data type.

Discussion

Applications may pass a NULL pointer but non-applications 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

OTOptionManagement

Determines an endpoint’s current or default option values or changes these values. (Deprecated in Mac OS X v10.4.)

OSStatus OTOptionManagement (
   EndpointRef ref,
   TOptMgmt *req,
   TOptMgmt *ret
);

Parameters
ref
req
ret
Return Value

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

Discussion

To use the OTOptionManagement function, you must have opened an endpoint using the OTOpenEndpoint or OTAsyncOpenEndpoint functions.

You use the OTOptionManagement function to negotiate, retrieve, or verify an endpoint’s protocol options. If the endpoint is in asynchronous mode and you have not installed a notifier function, it is not possible to determine when the function completes.

The action taken by the OTOptionManagement function is determined by the setting of the req->flags field. The following bulleted items describe the different operations that you can perform and the flag settings that you use to specify these operations.

Availability
Declared In
OpenTransport.h

OTRcv

Reads data sent using a connection-oriented transactionless protocol. (Deprecated in Mac OS X v10.4.)

OTResult OTRcv (
   EndpointRef ref,
   void *buf,
   OTByteCount nbytes,
   OTFlags *flags
);

Parameters
ref
buf

A pointer to a memory location where the incoming data is to be copied. You must allocate this buffer before you call the function.

nbytes
flags
Return Value

See the description of the OTResult data type.

Discussion

You call the OTRcv function to read data sent by the peer to which you are connected. If the OTRcv function succeeds, it returns an integer (OTStatus) specifying the number of bytes received. The function places the data read into the buffer referenced by the buf parameter. If the function fails, it returns a negative integer corresponding to a result code that indicates the reason for the failure. You can call this function to receive either normal or expedited data. If the data is expedited, the T_EXPEDITED flag is set in the flags parameter.

If T_MORE is set in the flags parameter when the function returns, this means that the buffer you allocated is too small to contain the data to be read and that you must call the OTRcv function again. If you have read x bytes with the first call, the next call to the OTRcv function begins to read at the (x + 1) byte. Of course, if you need it, you must copy the data in the buffer to another location before calling the function again. Each call to this function that returns with the T_MORE flag set means that you must call the function again to get more data. When you have read all the data, the OTRcv function returns with the T_MORE flag not set. If the endpoint does not support the concept of a TSDU (Transport Service Data Unit), the T_MORE flag is not meaningful and should be ignored. To determine whether the endpoint supports TSDUs, examine the tsdu field of the TEndpointInfo structure. A value of T_INVALID means that the endpoint does not support it.

Some protocols allow you to send zero-length data to signal the end of a logical unit. In this case, if you request more than 0 bytes when calling the OTRcv function, the function returns 0 bytes only to signal the end of a TSDU.

If the OTRcv function returns and the T_EXPEDITED bit is set in the flags parameter, this means that you are about to read expedited data. If the number of bytes of expedited data exceeds the number of bytes you specified in the reqCount parameter, both the T_EXPEDITED and the T_MORE bits are set. You must call the OTRcv function until the T_MORE flag is not set to retrieve the rest of the expedited data.

If you are calling the OTRcv function repeatedly to read normal data and a call to the function returns T_EXPEDITED in the flags parameter, the next call to the OTRcv function that returns without the T_EXPEDITED flag set returns normal data at the place it was interrupted. It is your responsibility to remember where that was and to continue processing normal data. You can determine how much normal data you read by maintaining a running total of the number of bytes returned in the OTStatus result.

If the endpoint is in asynchronous mode or is not blocking, the function returns with the kOTNoDataErr result if no data is available. If you have installed a notifier, the endpoint provider calls your notifier and passes T_DATA or T_EXDATA for the code parameter when there is data available. If you have not installed a notifier, you may poll for these events using the OTLook function. Once you receive a T_DATA or T_EXDATA event, you should continue in a loop, calling the OTRcv function until it returns with the kOTNoDataErr result.

If the endpoint is in synchronous mode and is blocking, the endpoint waits for data if none is currently available. You should avoid calling the OTRcv function this way because it might cause processing to hang if no data is available. If you are doing other operations in synchronous mode, you should put the endpoint in nonblocking mode before calling the OTRcv function.

Availability
Declared In
OpenTransport.h

OTRcvConnect

Reads the status of an outstanding or completed asynchronous call to theOTConnect function. (Deprecated in Mac OS X v10.4.)

OSStatus OTRcvConnect (
   EndpointRef ref,
   TCall *call
);

Parameters
ref
call
Return Value

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

Discussion

You call the OTRcvConnect function to determine the status of a previously issued OTConnect call. If you want to retrieve information about the connection, you must allocate buffers for the addr field and, if required, the opt and udata fields before you make the call.

If the endpoint is synchronous and blocking, the OTRcvConnect function waits for the connection to be accepted or rejected. If the connection is accepted, the function returns with a kOTNoError result. If the connection is rejected, the function returns with a kOTLookErr result. In this case, you should call the OTLook function to verify that a T_DISCONNECT event is the reason for the kOTLookErr, and then you should call the OTRcvDisconnect function to clear the event.

If the endpoint is asynchronous or nonblocking, the OTRcvConnect function returns with the kOTNoDataErr result if the connection has not yet been established.

Availability
Declared In
OpenTransport.h

OTRcvDisconnect

Identifies the cause of a connection break or of a connection rejection, acknowledges and clears the corresponding disconnection event. (Deprecated in Mac OS X v10.4.)

OSStatus OTRcvDisconnect (
   EndpointRef ref,
   TDiscon *discon
);

Parameters
ref
discon
Return Value

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

Discussion

Calling the OTRcvDisconnect function clears the corresponding disconnection event and retrieves any user data sent with the disconnection.

If you do not care about data returned with the disconnection and do not needto know the reason for the disconnection nor the sequence ID, you may specify a nil pointer for the discon parameter. In this case, the provider discards any user data associated with the disconnection.

The OTRcvDisconnect function behaves in the same way for all modes of operation. If there is no disconnection request pending, the function returns with the kOTNoDisconnectErr result. If there is a disconnection request pending, the function returns either the kOTNoError or kOTBufferOverflowErr result. In the latter instance, you need to check the discon field of the TEndpointInfo structure for your endpoint and make sure that the buffer referenced by the udata.buf field is at least as big as the value specified for the discon field.

Availability
Declared In
OpenTransport.h

OTRcvOrderlyDisconnect

Acknowledges a request for an orderly disconnect. (Deprecated in Mac OS X v10.4.)

OSStatus OTRcvOrderlyDisconnect (
   EndpointRef ref
);

Parameters
ref
Return Value

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

Discussion

The OTRcvOrderlyDisconnect function is a service that is not supported by all protocols. If it is, the servtype field of the TEndpointInfo structure has the value T_COTS_ORD or T_TRANS_ORD for the endpoint.

After using the OTRcvOrderlyDisconnect function to acknowledge receipt of a disconnection request, there will not be any more data to receive. Calls to the OTRcv function (for a transactionless connection) or to the OTRcvRequest function (for a transaction-based connection) after acknowledging a disconnection request fail with the kOTOutStateErr result. If the endpoint supports a remote orderly disconnect, you can still send data over the connection if you have not yet called the OTSndOrderlyDisconnect function.

The OTRcvOrderlyDisconnect function behaves in the same way in all modes of operation. If there is no disconnection request pending, the function returns with the kOTNoReleaseErr result. It there is a disconnection request pending, the function returns either the kOTNoError or kOTBufferOverflowErr result. In the latter instance, you need to check the discon field of theTEndpointInfo structure for your endpoint and make sure that the buffer referenced by the udata.buf field is at least as big as the value specified for the discon field.

Availability
Declared In
OpenTransport.h

OTRcvUData

Reads data sent by a client using a connectionless transactionless protocol. (Deprecated in Mac OS X v10.4.)

OSStatus OTRcvUData (
   EndpointRef ref,
   TUnitData *udata,
   OTFlags *flags
);

Parameters
ref
udata
flags
Return Value

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

Discussion

When the OTRcvUData function returns, it passes a pointer to a TUnitData structure containing information about the data read and a pointer to a flags variable that is set to indicate whether there is more data to be retrieved. If the buffer pointed to by the udata->udata.buf field is not large enough to hold the current data unit, the endpoint provider fills the buffer and sets the flags parameter to T_MORE to indicate that you must call the OTRcvUData function again to receive additional data. Subsequent calls to the OTRcvUData function return 0 for the length of the address and option buffers until you receive the full data unit. The last unit to be received does not have the T_MORE flag set.

If the endpoint is in asynchronous mode or is not blocking and data is not available, the OTRcvUData function fails with the kOTNoDataErr result. The endpoint provider uses the T_DATA event to notify the endpoint when data becomes available. You can use a notifier function or the OTLook function to retrieve the event. Once you get the T_DATA event, you should continue calling the OTRcvUData function until it returns the kOTNoDataErr result.

It is possible that the provider generates an erroneous T_DATA event. This is the case when the provider calls your notifier, passing T_DATA for the code parameter; but when you execute the OTRcvUData function, it returns with a kOTNoDataErr result. If this happens, you should continue normal processing and assume that the next T_DATA event is genuine.

Availability
Declared In
OpenTransport.h

OTRcvUDErr

Clears an error condition indicated by a T_UDERR event and returns the reason for the error. (Deprecated in Mac OS X v10.4.)

OSStatus OTRcvUDErr (
   EndpointRef ref,
   TUDErr *uderr
);

Parameters
ref
uderr
Return Value

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

Discussion

You use the OTRcvUDErr function if you have called the OTSndUData function and the endpoint provider has issued the T_UDERR event to indicate that the send operation did not succeed. This usually happens when the endpoint provider cannot determine immediately that you have specified a bad address or option value. For example, assume that you are using AppleTalk and you specify an NBP address. If Open Transport cannot resolve the address, it sends a T_UDERR event to your notifier function. To clear the error condition and determine the cause of the failure, you must call the OTRcvUDErr function.

If the size of the option or error data returned exceeds the size of the allocated buffers, the OTRcvUDErr function returns with the result kOTBufferOverflowErr, but the error indication is cleared anyway.

If you do not need to identify the cause of the failure, you can set the uderr pointer to nil. In this case, the OTRcvUDErr function clears the error indication without reporting any information to you. It is important, nevertheless, that you actually call the OTRcvUDErr function to clear the error condition. If you don’t call this function, the endpoint remains in an invalid state for doing other send operations, and the endpoint provider is unable to deallocate memory reserved for internal buffers associated with the send operation.

Availability
Declared In
OpenTransport.h

OTReadBuffer

Copies data out of a no-copy receive buffer. (Deprecated in Mac OS X v10.4.)

Boolean OTReadBuffer (
   OTBufferInfo *buffer,
   void *dest,
   OTByteCount *len
);

Parameters
buffer
dest
len
Availability
Declared In
OpenTransportProtocol.h

OTRegisterAsClientInContext

Registers your application as a client of Open Transport and gives Open Transport a notifier function it can use to send you events. (Deprecated in Mac OS X v10.4.)

OSStatus OTRegisterAsClientInContext (
   OTClientName name,
   OTNotifyUPP proc,
   OTClientContextPtr clientContext
);

Parameters
name
proc
clientContext
Return Value

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

Availability
Declared In
OpenTransport.h

OTRegisterName

Registers an entity name on the network. (Deprecated in Mac OS X v10.4.)

OSStatus OTRegisterName (
   MapperRef ref,
   TRegisterRequest *req,
   TRegisterReply *reply
);

Parameters
ref
req
reply
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 OTRegisterName function to make a name visible on the network to other network devices.

Some protocol implementations under Open Transport allow a client to specify a name rather than an address when binding the endpoint using the OTBind function. Binding an endpoint by name causes the protocol to automatically register the name on the network if the protocol supports dynamic name registration. This is the simpler technique for registering a name and is preferred over creating a mapper provider and then using the OTRegisterName function to register the name.

The format for the requested name and address is specific to the protocol used. Please consult the documentation for the protocol you are using for format information.

Availability
Declared In
OpenTransport.h

OTReleaseBuffer

Returns the no-copy receive buffer to the system. (Deprecated in Mac OS X v10.4.)

void OTReleaseBuffer (
   OTBuffer *buffer
);

Parameters
buffer
Availability
Declared In
OpenTransportProtocol.h

OTRemoveFirst

Removes the first link in a FIFO list. (Deprecated in Mac OS X v10.4.)

OTLink * OTRemoveFirst (
   OTList *list
);

Parameters
list
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTRemoveLast

Removes the last link in a FIFO list. (Deprecated in Mac OS X v10.4.)

OTLink * OTRemoveLast (
   OTList *list
);

Parameters
list
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTRemoveLink

Removes the last link in a FIFO list. (Deprecated in Mac OS X v10.4.)

Boolean OTRemoveLink (
   OTList *list,
   OTLink *link
);

Parameters
list
link
Availability
Declared In
OpenTransport.h

OTRemoveNotifier

Removes a provider’s notifier function. (Deprecated in Mac OS X v10.4.)

void OTRemoveNotifier (
   ProviderRef ref
);

Parameters
ref
Discussion

The OTRemoveNotifier function removes the notifier (if any) currently installed for the provider specified by the ref parameter.

Availability
Declared In
OpenTransport.h

OTResolveAddress

Returns the protocol address that corresponds to the name of an endpoint. (Deprecated in Mac OS X v10.4.)

OSStatus OTResolveAddress (
   EndpointRef ref,
   TBind *reqAddr,
   TBind *retAddr,
   OTTimeout timeOut
);

Parameters
ref
reqAddr
retAddr
timeOut
Return Value

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

Discussion

The OTResolveAddress function returns the lowest-level address for your endpoint. Not all endpoints support this function. A value of CAN_RESOLVE_ADDR in the flags field of the TEndpointInfo structure indicates that the endpoint does support this function. Using this function saves you the trouble of opening and closing a mapper provider if the only reason you have for opening the mapper is to look up the address corresponding to a specific endpoint name. You would still have to open the mapper if you needed to look up a name pattern—that is, if the name included any wildcard characters.

You are responsible for initializing the buffers described by the req and ret parameters required to hold the addresses. To determine how large these buffers should be, examine the addr field of the TEndpointInfo structure, which specifies the maximum amount of memory needed to store an address for the endpoint specified by the ref parameter.

If a notifier is not installed, it is not possible to determine when the OTResolveAddress function completes.

Availability
Declared In
OpenTransport.h

OTReverseList

Reverses the order in which entries are linked in a list. (Deprecated in Mac OS X v10.4.)

OTLink * OTReverseList (
   OTLink *list
);

Parameters
list
Return Value

See the description of the OTLink data type.

Availability
Declared In
OpenTransport.h

OTScheduleDeferredTask

Schedules a task for execution at deferred task time. (Deprecated in Mac OS X v10.4.)

Boolean OTScheduleDeferredTask (
   OTDeferredTaskRef dtCookie
);

Parameters
dtCookie
Discussion

The OTScheduleDeferredTask function schedules for execution at the next deferred task time the task associated with the dtCookie parameter, which is the reference returned by the OTCreateDeferredTask function.

You can call this function at any time. If you have not yet destroyed a task, you can use this function to reschedule the same task more than once.

If you makes multiple calls to the OTScheduleDeferredTask function before the task is executed, additional tasks are not scheduled; only one instance of each unique task can only be scheduled at a time.

This function returns true if it scheduled the deferred task successfully, false if not. If it returns false and the dtCookie parameter has a valid value (other than 0), then the task is already scheduled to run. If dtCookie is invalid (a value of 0), the function returns false and does nothing.

If you want to call Open Transport from an interrupt, you can use this function (and the OTCreateDeferredTask function) instead of the standard Deferred Task Manager function DTInstall to create a deferred task that permits you to call Open Transport function calls. This allows Open Transport to adapt to changes in the underlying operating system without affecting the client’s code.

Availability
Declared In
OpenTransport.h

OTScheduleTimerTask

Schedules a timer task to be executed at the specified time. (Deprecated in Mac OS X v10.4.)

Boolean OTScheduleTimerTask (
   OTTimerTask timerTask,
   OTTimeout milliSeconds
);

Parameters
timerTask
milliSeconds
Availability
Declared In
OpenTransportProtocol.h

OTSetAddressFromNBPEntity

Stores an NBP entity structure as an NBP address string. (Deprecated in Mac OS X v10.4.)

OTByteCount OTSetAddressFromNBPEntity (
   UInt8 *nameBuf,
   const NBPEntity *entity
);

Parameters
nameBuf

A pointer to the NBP address buffer in which you wish to store the NBP entity.

entity
Return Value

See the description of the OTByteCount data type.

Discussion

The OTSetAddressFromNBPEntity function stores the information in the NBP entity into the buffer specified by the nameBuf parameter in the format required for mapper calls—that is, if you have a backslash (\), a colon (:), or an at-sign (@) in your NBP name, this function inserts a backslash before each so that the mapper functions can handle them correctly. This function returns the number of bytes that were actually used in the buffer.

Availability
Declared In
OpenTransportProviders.h

OTSetAddressFromNBPString

Copies an NBP name string into an NBP address buffer. (Deprecated in Mac OS X v10.4.)

OTByteCount OTSetAddressFromNBPString (
   UInt8 *addrBuf,
   const char *name,
   SInt32 len
);

Parameters
addrBuf

A pointer to the NBP address buffer in which to store the NBP name string.

name

A pointer to the NBP name string you wish to copy into the buffer.

len

The number of characters to copy.

Return Value

See the description of the OTByteCount data type.

Discussion

The OTSetAddressFromNBPString function copies the string indicated by the nbpName parameter into the buffer indicated by the addrBuf parameter. The len parameter indicates the number of characters to copy. A value of -1 copies the entire nbpName string. The function returns the number of bytes actually copied.

Availability
Declared In
OpenTransportProviders.h

OTSetAsynchronous

Sets a provider’s mode of execution to asynchronous. (Deprecated in Mac OS X v10.4.)

OSStatus OTSetAsynchronous (
   ProviderRef ref
);

Parameters
ref
Return Value

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

Discussion

The OTSetAsynchronous function causes all functions for the provider specified in the ref parameter to run asynchronously. You must install a notifier function for the provider if it needs to receive completion events. You can install a notifier function either before or after calling the OTSetAsynchronous function.

Changing a provider’s mode of execution does not affect its notifier function, if any; the notifier function remains installed.

Availability
Declared In
OpenTransport.h

OTSetBit

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

Boolean OTSetBit (
   UInt8 *bitMap,
   OTByteCount bitNo
);

Parameters
bitMap
bitNo
Availability
Declared In
OpenTransportProtocol.h

OTSetBlocking

Allows a provider to wait or block until it is able to send or receive data. (Deprecated in Mac OS X v10.4.)

OSStatus OTSetBlocking (
   ProviderRef ref
);

Parameters
ref
Return Value

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

Discussion

The OTSetBlocking function causes provider functions that send or receive data to wait if current conditions prevent them from completing an operation. By default, a provider is in nonblocking mode, in which case, if a provider function were unable to complete sending or receiving data, it would return immediately with a result that would tell you why the operation was unable to complete.

If a provider is in blocking mode and you call the OTCloseProvider function to close the provider, Open Transport gives each Streams module up to 15 seconds to process outgoing commands. It is recommended that you call the OTSetNonBlocking function before you call the OTCloseProvider function.

Availability
Declared In
OpenTransport.h

OTSetBusTypeInPortRef

Sets bus type for a port reference. (Deprecated in Mac OS X v10.4.)

OTPortRef OTSetBusTypeInPortRef (
   OTPortRef ref,
   OTBusType busType
);

Parameters
ref
busType
Return Value

See the description of the OTPortRef data type.

Availability
Carbon Porting Notes

OT ports are read only in Carbon. In Mac OS X, code that communicates directly with network interfaces must use the IOKit API.

Declared In
OpenTransport.h

OTSetDeviceTypeInPortRef

Sets device type for a port reference. (Deprecated in Mac OS X v10.4.)

OTPortRef OTSetDeviceTypeInPortRef (
   OTPortRef ref,
   OTDeviceType devType
);

Parameters
ref
devType
Return Value

See the description of the OTPortRef data type.

Availability
Carbon Porting Notes

OT ports are read only in Carbon. In Mac OS X, code that communicates directly with network interfaces must use the IOKit API.

Declared In
OpenTransport.h

OTSetFirstClearBit

Atomcially sets the first clear bit in a specified bit map. (Deprecated in Mac OS X v10.4.)

OTResult OTSetFirstClearBit (
   UInt8 *bitMap,
   OTByteCount startBit,
   OTByteCount numBits
);

Parameters
bitMap
startBit
numBits
Return Value

See the description of the OTResult data type.

Discussion

Sets the first clear bit in bitMap , starting with startBit and giving up after numBits. Returns the bit number that was set, or a kOTNotFoundErr error if there was no clear bit available

Availability
Declared In
OpenTransportProtocol.h

OTSetNBPEntityFromAddress

Parses and stores an NBP address into an NBP entity. (Deprecated in Mac OS X v10.4.)

Boolean OTSetNBPEntityFromAddress (
   NBPEntity *entity,
   const UInt8 *addrBuf,
   OTByteCount len
);

Parameters
entity
addrBuf

A pointer to the address buffer in which to store the NBP name string.

len
Discussion

The OTSetNBPEntityFromAddress function parses an NBP address or a combined DDP-NBP address into the NBP name’s constituent parts (name, type, and zone) and stores the result in an NBP entity. The function ignores the DDP address part of a combined DDP-NBP address. From the NBP entity, each of the constituent parts of the name can be later retrieved or changed.

This function returns true if it worked successfully; it returns false if it had to truncate any data—that is, if the address had data that was too long in one of the fields, each of which only holds 32 characters of data. When this occurs, Open Transport still stores the data, but in a truncated form.

Availability
Declared In
OpenTransportProviders.h

OTSetNBPName

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

Boolean OTSetNBPName (
   NBPEntity *entity,
   const char *name
);

Parameters
entity
name

A pointer to the name portion of an NBP name string that you wish to store.

Discussion

The OTSetNBPName function stores the NBP name specified by the name parameter into the NBP entity structure indicated by the nbpEntity parameter, deleting any previous name stored there. This function returns false if the name parameter is longer than the maximum allowed for a name part of an NBP name (32 characters).

Availability
Declared In
OpenTransportProviders.h

OTSetNBPType

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

Boolean OTSetNBPType (
   NBPEntity *entity,
   const char *typeVal
);

Parameters
entity
typeVal

A pointer to the type portion of an NBP name string that you wish to store.

Discussion

The OTSetNBPType function stores the NBP type specified by the type parameter into the NBP entity structure indicated by the nbpEntity parameter, deleting any previous type stored there. The type supplied must not have any escape characters stored in it, although you do not receive any error message if you do use such characters. This function returns false if the type parameter is longer than the maximum allowed for type part of an NBP name (32 characters).

Availability
Declared In
OpenTransportProviders.h

OTSetNBPZone

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

Boolean OTSetNBPZone (
   NBPEntity *entity,
   const char *zone
);

Parameters
entity
zone

A pointer to the zone portion of an NBP name string that you wish to store.

Discussion

The OTSetNBPZone function stores the NBP zone specified by the zone parameter into the NBP entity structure indicated by the nbpEntity parameter, deleting any previous zone stored there. The zone supplied must not have any of the NBP escape characters stored in it, although you do not receive any error message if you do use such characters. This function returns false if the zone parameter is longer than the maximum allowed for zone part of an NBP name (32 characters).

Availability
Declared In
OpenTransportProviders.h

OTSetNonBlocking

Disallows a provider from waiting if it cannot currently complete a function that sends or receives data. (Deprecated in Mac OS X v10.4.)

OSStatus OTSetNonBlocking (
   ProviderRef ref
);

Parameters
ref
Return Value

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

Discussion

The OTSetNonBlocking function causes provider functions to return a result code immediately, instead of waiting for a function that sends or receives data to complete. When you open a provider, its mode of operation is set to nonblocking by default.

Availability
Declared In
OpenTransport.h

OTSetSynchronous

Sets a provider’s mode of execution to synchronous. (Deprecated in Mac OS X v10.4.)

OSStatus OTSetSynchronous (
   ProviderRef ref
);

Parameters
ref
Return Value

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

Discussion

The OTSetSynchronous function causes all provider functions to run synchronously when using the provider that you specify.

Changing a provider’s mode of execution does not affect its notifier function, if any is installed for this provider; the notifier function remains installed.

Availability
Declared In
OpenTransport.h

OTSnd

Sends data to a remote peer. (Deprecated in Mac OS X v10.4.)

OTResult OTSnd (
   EndpointRef ref,
   void *buf,
   OTByteCount nbytes,
   OTFlags flags
);

Parameters
ref
buf

A pointer to the data being sent. If you are sending data that is not stored contiguously, this is a pointer to an OTData structure that describes the first data fragment.

nbytes
flags
Return Value

See the description of the OTResult data type.

Discussion

You use the OTSnd function to send data to a remote peer. Before you use this function, you must establish a connection with the peer.

If the OTSnd function succeeds, it returns an integer (OSStatus) specifying the number of bytes that were actually sent. If it fails, it returns a negative integer corresponding to a result code that indicates the reason for the failure.

You specify the data to be sent by passing a pointer to the data (buf) and byspecifying the size of the data (nbytes). The maximum size of the data you can send is specified by the tsdu field of the TEndpointInfo structure for the endpoint.

Some protocols use expedited data for control or attention messages. To determine whether the endpoint supports this service, examine the etsdu field of the TEndpointInfo structure. A positive integer for the etsdu field indicates the maximum size in bytes of expedited data that you can send. To send expedited data, you must set the T_EXPEDITED bit of the flags parameter.

If you want to break up the data sent into smaller logical units, you can set the T_MORE bit of the flags parameter to indicate that you are using additional calls to the OTSnd function to send more data that belongs to the same logical unit. To indicate that the last data unit is being sent, you must specify 0 for nbytes and turn off the T_MORE flag. This is the only circumstance under which it is permitted to send a zero-length data unit. If the endpoint does not support the sending of zero-length data, the OTSnd function fails with the kOTBadDataErr result.

If the endpoint is in blocking mode, the OTSnd function returns after it actually sends the data. If flow-control restrictions prevent its sending the data, it retries the operation until it is able to send it. If the endpoint is in nonblocking mode, the OTSnd function returns with the kOTFlowErr result if flow-control restrictions prevent the data from being sent. When the endpoint provider is able to send the data, it returns a T_GODATA event to let you know that it is possible to send data.

The following table shows how the endpoint’s mode of execution and blocking status affects the behavior of the OTSnd function.

Table A-1  

Blocking

Nonblocking

Synchronous

The function returns when the provider lifts flow-control restrictions The kOTFlowErr result is never returned.

The function returns immediately. The kOTFlowErr result might be returned.

Asynchronous

The function returns immediately. The kOTFlowErr result is never returned.

The function returns immediately. The kOTFlowErr result might be returned.
Availability
Declared In
OpenTransport.h

OTSndDisconnect

Tears down an open connection (abortive disconnect) or rejects an incoming connection request. (Deprecated in Mac OS X v10.4.)

OSStatus OTSndDisconnect (
   EndpointRef ref,
   TCall *call
);

Parameters
ref
call
Return Value

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

Discussion

There are two functions that you can use to tear down a connection: OTSndDisconnect for an abortive disconnect, or OTSndOrderlyDisconnect for an orderly disconnect. It is recommended that you use the OTSndOrderlyDisconnect function for tearing down a connection whenever possible and that you use the OTSndDisconnect function only for rejecting incoming connection requests.

If the endpoint is in asynchronous mode, the OTSndDisconnect function returns immediately with a result of kOTNoError to indicate that the disconnection process has begun and that your notifier function will be called when the process completes.

When the connection has been broken, the provider issues a T_DISCONNECTCOMPLETE event. If you have installed a notifier function, Open Transport calls your notifier and passes this event in the code parameter. The cookie parameter contains the call parameter. If you have not installed a notifier function, you cannot determine when this function completes.

Availability
Declared In
OpenTransport.h

OTSndOrderlyDisconnect

Initiates or completes an orderly disconnection. (Deprecated in Mac OS X v10.4.)

OSStatus OTSndOrderlyDisconnect (
   EndpointRef ref
);

Parameters
ref
Return Value

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

Discussion

You call the OTSndOrderlyDisconnect function to initiate an orderly release of a connection and to indicate to the peer endpoint that you have no more data to send. After calling this function, you must not send any more data over the connection. However, you can still continue to receive data if the peer endpoint has not yet called the OTSndOrderlyDisconnect function.

This function is a service that is not supported by all protocols. If it is supported, the servtype field of the TEndpointInfo structure has the value T_COTS_ORD or T_TRANS_ORD.

The OTSndOrderlyDisconnect function behaves exactly the same in all modes of operation.

Availability
Declared In
OpenTransport.h

OTSndUData

Sends data using a connectionless transactionless endpoint. (Deprecated in Mac OS X v10.4.)

OSStatus OTSndUData (
   EndpointRef ref,
   TUnitData *udata
);

Parameters
ref
udata

A pointer to a TUnitData structure that specifies thedata to be sent and its destination.

Return Value

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

Discussion

If the endpoint is in synchronous, blocking mode, the OTSndUData function returns immediately. If flow-control restrictions prevent its sending the data, it retries the operation until it is able to send it. If the endpoint is in nonblocking mode, the OTSndUData function returns a kOTFlowErr result if flow-control restrictions prevent the data from being sent. When the endpoint provider is able to send the data, it calls your notifier function, passing T_GODATA for the code parameter. You can then call the OTSndUData function from your notifier to send the data. You can also retrieve this event by polling the endpoint using the OTLook function.

Some endpoint providers are not able to detect immediately whether you specified incorrect address or option information. In such cases, the provider calls your notifier function when it detects the error, passing the T_UDERR for the code parameter to advise you that an error has occurred. You can determine the cause of this event by calling the OTRcvUDErr function and examining the value of the uderr->error parameter. It is important that you call the OTRcvUDErr function even if you are not interested in examining the cause of the error. Failing to do this leaves the endpoint in an invalid state for doing other sends and makes the endpoint provider unable to deallocate memory reserved for internal buffers associated with the send.

The next table shows how the endpoint’s mode of execution and blocking status affects the behavior of the OTSndUData function.

Table A-2  

Blocking

Nonblocking

Synchronous

The function returns when the provider lifts flow-control restrictions The kOTFlowErr result is never returned.

The function returns immediately. the kOTFlowErr result might be returned

Asynchronous

The function returns immediately. The kOTFlowErr result is never returned.

the function returns immediately. the kOTFlowErr result might be returned.
Availability
Declared In
OpenTransport.h

OTStrCat

Concatenates two C strings. (Deprecated in Mac OS X v10.4.)

void OTStrCat (
   char *dest,
   const char *src
);

Parameters
dest
src
Availability
Declared In
OpenTransport.h

OTStrCopy

Copies a C string. (Deprecated in Mac OS X v10.4.)

void OTStrCopy (
   char *dest,
   const char *src
);

Parameters
dest
src
Availability
Declared In
OpenTransport.h

OTStrEqual

Determines whether two C strings are the same. (Deprecated in Mac OS X v10.4.)

Boolean OTStrEqual (
   const char *src1,
   const char *src2
);

Parameters
src1
src2
Availability
Declared In
OpenTransport.h

OTStrLength

Returns the length of a C string. (Deprecated in Mac OS X v10.4.)

OTByteCount OTStrLength (
   const char *str
);

Parameters
str
Return Value

See the description of the OTByteCount data type.

Availability
Declared In
OpenTransport.h

OTSubtractTimeStamps

Subtracts one timestamp value from another. (Deprecated in Mac OS X v10.4.)

OTTimeStamp * OTSubtractTimeStamps (
   OTTimeStamp *result,
   OTTimeStamp *startTime,
   OTTimeStamp *endEnd
);

Parameters
result
startTime
endEnd
Return Value

See the description of the OTTimeStamp data type.

Availability
Declared In
OpenTransport.h

OTTestBit

Atomically tests a bit in a specified bit map. (Deprecated in Mac OS X v10.4.)

Boolean OTTestBit (
   UInt8 *bitMap,
   OTByteCount bitNo
);

Parameters
bitMap
bitNo
Availability
Declared In
OpenTransportProtocol.h

OTTimeStampInMicroseconds

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

UInt32 OTTimeStampInMicroseconds (
   OTTimeStamp *delta
);

Parameters
delta
Availability
Declared In
OpenTransport.h

OTTimeStampInMilliseconds

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

UInt32 OTTimeStampInMilliseconds (
   OTTimeStamp *delta
);

Parameters
delta
Availability
Declared In
OpenTransport.h

OTUnbind

Dissociates an endpoint from its address or cancels an asynchronous call to the OTBind function. (Deprecated in Mac OS X v10.4.)

OSStatus OTUnbind (
   EndpointRef ref
);

Parameters
ref
Return Value

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

Discussion

If you call the OTUnbind function asynchronously and you have not installed a notifier function, the only way to determine that the endpoint has been unbound is to use the OTGetEndpointState function to poll the state of the endpoint. The function returns the kOTStateChangeErr result when the OTUnbind function returns. If the function succeeds, the state of the endpoint is T_UNBND. If it fails, its state is T_IDLE.

After you unbind an endpoint, you can no longer use it to send or receive information. You can use the OTCloseProvider function to deallocate memory reserved for the endpoint, or you can use the OTBind function to associate it with another address and then resume transferring data or establishing a connection.

Availability
Declared In
OpenTransport.h

OTUnregisterAsClientInContext

Removes your application as a client of Open Transport. (Deprecated in Mac OS X v10.4.)

OSStatus OTUnregisterAsClientInContext (
   OTClientContextPtr clientContext
);

Parameters
clientContext
Return Value

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

Availability
Declared In
OpenTransport.h

OTUseSyncIdleEvents

Allows synchronous idle events to be sent to your notifier. (Deprecated in Mac OS X v10.4.)

OSStatus OTUseSyncIdleEvents (
   ProviderRef ref,
   Boolean useEvents
);

Parameters
ref
useEvents
Return Value

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

Availability
Declared In
OpenTransport.h

< Previous PageNext Page > Hide TOC

© 2005 Apple Computer, Inc. All Rights Reserved. (Last updated: 2005-07-07)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.