Legacy Document

Inside Macintosh: Networking With Open Transport / Part 2 - Open Transport Reference

Chapter 22 - 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,
                     UInt32 fields,
                     OSStatus* err = NULL);

PARAMETERS

ref

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

structType

A 32-bit value 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 .

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. See Discussion for more information.

You can specify one or more constant names for the fields parameter. See Discussion for the value and meaning of these names. To specify more than one constant name, use the bitwise OR operator to combine values.

err

A result code. See Appendix B for more information.

DISCUSSION

The OTAlloc function allocates a data structure for use in a subsequent endpoint call. You use the structType parameter to specify the structure to be allocated and the fields parameter to specify the substructures to be allocated. Possible field values are given by the following enumeration

enum 
{
   T_ADDR   = 0x01,  /* for address information */
   T_OPT    = 0x02,  /* for option information */
   T_UDATA  = 0x04,  /* for data */
   T_ALL    = 0xffff /* for address, option, and data */
};

If the OTAlloc function succeeds, it returns a pointer to the desired structure.

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 bufferis. 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.

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

Note

If you just want to allocate a block of memory, consider using the OTAllocMem function.

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.

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.

You must not use the pointer returned by the OTAlloc function in calls to any other endpoint as other endpoints mayhave different sizes.

SEE ALSO

The OTFree function.

The TBind structure.

The TEndpointInfo structure.

The OTAllocMem function and the OTFreeMem function .

Table 4-4.