Inside Macintosh: Open Transport /

Chapter 5 - Option Management / 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

OSErr OTCreateOptions (const char* prtclName; char** strPtr, 
                       TNetbuf* buf);

C++ INTERFACE

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

PARAMETERS

prtclName

The name of the protocol for which the option is set. 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.

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.

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 value specified by the TEndpoint.options field for this endpoint. You set buf->len to 0. When the function returns, it sets the buf->len field to the actual length of the option information, including padding.

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.

DESCRIPTION

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->opt field. 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 table below 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" on page 5-9.

SEE ALSO

You use the buffer constructed by the OTCreateOptions function as part of the req parameter to the OTOptionManagement function (page 5-34). Listing 5-2 on page 5-20 shows how you use the OTCreateOptions function.

You use the OTCreateOptionString function, described in the next section, to reverse the process and construct a string containing endpoint option values by parsing a buffer containing TOption structures.