Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Allocating Structures

OTAlloc

Allocates an XTI data structure.

C INTERFACE

void* OTAlloc (EndpointRef ref, OTStructType structType,
               UInt32 fields, OSStatus* err);

C++ INTERFACE

void* TEndpoint::Alloc(OTStructType structType, int fields,
                       OSStatus* err = NULL);

PARAMETERS

ref

The endpoint reference of the endpoint for which the data structure is allocated.

structType

A long specifying the constant name of the structure for which memory is to be allocated. Possible values for the structType parameter are given by the structure types enumeration (page 3-47).

fields

An integer specifying the structure fields for which buffers are to be allocated.

Each structure that you can specify for structType, except for T_INFO, contains at least one field of type TNetbuf. For each such field, you can use the fields parameter to specify that the buffer described by TNetbuf also be allocated. The length of the allocated buffer is at least as large as the size returned for the endpoint by the OTGetEndpointInfo function. For each buffer allocated, the OTAlloc function sets the maxlen field to the length of the buffer and sets the len field to 0.

You can specify one or more constant names for the fields parameter. Possible values for constant names are given by the buffer types enumeration (page 3-42). To specify more than one constant name, use the bitOR operator to combine values.

DESCRIPTION

The OTAlloc function allocates a data structure for use in a subsequent call. You use the structType parameter to specify the structure to be allocated and the fields parameter to specify the substructures to be allocated. If the OTAlloc function succeeds, it returns a pointer to the desired structure. The OTAlloc function is provided mainly for compatibility with XTI. Although using this function along with the OTFree function can save you coding work, this is at the price of slower performance. In general, you should not allocate and free structures on every call. Instead, you should declare structures that are to be passed as parameters to endpoint functions just as you would any other variables or data structures.

It is easiest to understand what the OTAlloc function does by considering what you would have to do if you did not use it. If you declared structType structures as normal data structures, you would have to declare the data structure and then initialize the maxlen and buf fields of every TNetbuf type field contained by the structure. To determine the appropriate size of each buffer, you would have to call the OTGetEndpointInfo function. For example, if you call the OTGetProtAddress function to get the protocol address of an endpoint, you must pass a parameter of type TBind. The addr.buf field of the TBind structure points to a buffer that is large enough to hold the endpoint's protocol address. To determine how large the buffer has to be, you call the OTGetEndpointInfo function; then you allocate the memory for the buffer and initialize the addr.buf field to point to the buffer and initialize the addr.maxlen field to specify how large the buffer can be. The OTAlloc function does all this work for you. Given the previous example, if you make the call

TBind* boundAddr = OTAlloc(T_BIND, T_ADDR);

the OTAlloc function allocates the TBind structure, initializes the TNetbuf field that is used to describe the endpoint address, and allocates memory for the buffer in which the address is to be stored. All buffers allocated are guaranteed to be of the appropriate size for the kind of endpoint specified by the ref parameter. You must not use the pointer returned by the OTAlloc function in calls to any other endpoint.

If the requested structure contains TNetbuf fields and you do not specify these fields using the fields parameter, the OTAlloc function sets the maxlen, len, and buf fields of these TNetbuf structures to 0.

SPECIAL CONSIDERATIONS

If you specify T_UDATA or T_ALL for the fields parameter and the endpoint information structure defines the tsdu or etsdu size for the endpoint to be of infinite length, the OTAlloc function does not allocate a data buffer for the endpoint.

VALID STATES

All

SEE ALSO

To deallocate memory allocated with the OTAlloc function, use the OTFree function (described next).

You use the structure types enumeration (page 3-47) to specify the structure for which memory is to be allocated.

You use the buffer types enumeration (page 3-42) to specify which TNetbuf structures should be allocated for the structure type you select.

The TBind structure (page 3-51) specifies the address of an endpoint.

The TEndpointInfo structure (page 3-48) specifies the maximum size of buffers used to hold an endpoint's address, options, and data.

To allocate raw memory, use the OTAllocMem function, and to deallocate the allocated raw memory, use the OTFreeMem function, both described in the chapter "Process Management."