Legacy Document

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

Chapter 25 - Option Management Reference / Functions

Manipulating the Format of Option Information /

OTCreateOptions

Writes option information into a buffer, from a string specifying option values.

C INTERFACE

OSStatus OTCreateOptions (const char* endptName, char** strPtr, 
                                         TNetbuf* buf);

C++ INTERFACE

None. C++ applications use the C interface to this function.

PARAMETERS

endptName

The name of the protocol for which the options are specified. For example, for an AppleTalk endpoint this might be "atp" or "ddp."

strPtr

A pointer to a pointer to a string containing option information. If an error occurs in writing the option information to the buffer, strPtr points to the position in the string where the error occurred.

buf

A pointer to a TNetbuf structure that specifies the size and location of the buffer into which the function writes option information. You must allocate the buffer and set the buf->opt field to point to it.

You must set the buf->maxlen field to the size of the buffer. To handle all possible options, create a buffer whose size is equal to the value specified by the TEndpoint.options field for an endpoint configured using the endptName string.

The function appends option information to the buffer beginning at the offset specified by the buf->len field. Set this field to 0 to start at the beginning of the buffer. When the function returns, the value of the buf->len field is updated to reflect the new length, including padding.

function result

See Discussion.

DISCUSSION

The OTCreateOptions function automates the construction of a buffer that describes endpoint option values for a particular protocol. Given a string, a pointer to a buffer, and the protocol for which the options are set, the function constructs TOption structures describing each option specified and then places these structures in the buffer referenced by the buf parameter. After using the OTCreateOptions function to construct the buffer, you have most of the information needed to create the req parameter to the OTOptionManagement function.

The string containing option values has the format:

optionName1 = value optionName2 = value optionName3 = value [....]

where value can be a numeric value, a string value, or a byte array value. The next table describes how each value is represented.

Format of values	Contents
Numeric	A minus sign (-) prefix for negative numbers, followed by the digits comprising the number; for example, -6784. A $ or 0x prefix for hexadecimal numbers, followed by the digits comprising the number; for example, $FFFE.
String	The option string, which is composed of a delimiter character, followed by the characters comprising the string, followed by the delimiter character. A delimiter character is the first non- blank character after the equals sign. For example, SomeOptionName = *The String Option*, or SomeOtherOptionName = %Another String Option%.
Byte array	A leading $ or 0x followed by a sequence of hex digits with no intervening spaces or tabs. There must be an even number of digits; for example, $FF12EE46.

Possible values for option names are given in the documentation for the protocol you are using. Generic option names are described in "XTI-Level Options and General Options".

Open Transport maintains an internal database relating to options and their values. Open Transport might not be able to write option information to the buffer because it cannot match a name or value you have specified with a name or value in its database. This is either because you misspelled a name or specified a value that is out of range or because the option you want to configure is not included in Open Transport's data base. The latter might be the case for an option that is rarely used.

SPECIAL CONSIDERATIONS

The option names used by this function are not localised. Thus, you should never present these option strings to users.

SEE ALSO

The OTCreateOptionString function.