Inside Macintosh: Open Transport /

Chapter 5 - Option Management / Option Management Reference

Functions / Determining and Changing Function Values

OTOptionManagement

Determines an endpoint's current or default option values or changes
these values.

C INTERFACE

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

C++ INTERFACES

OSErr TEndpoint::OptionManagement(TOptMgmt* req, TOptMgmt* ret);

PARAMETERS

ref

The endpoint reference of the endpoint for which you are checking or setting option values.

req

A pointer to an option management structure (page 5-33), which describes the action to be taken by the function and the options affected.

ret

A pointer to an option management structure (page 5-33), which describes the options that were changed or returned by the function and how successful the negotiation process was.

DESCRIPTION

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.

• To negotiate values for the endpoint, you must call the OTOptionManagement function, specifying T_NEGOTIATE for the req->flags field. The endpoint provider evaluates the requested options, negotiates the values, and returns the resulting values in the option management structure pointed to by the ret->opt.buf field. The status field of each returned option is set to a constant that indicates the result of the negotiation. These constants are described by the status codes enumeration (page 5-29).

  For any protocol specified, you can negotiate for the default values of all options supported by the endpoint by specifying the value T_ALLOPT for the name field of the TOption structure. This might be useful if you want to change current settings or if negotiations for other values have failed. The success of the negotiations depends partly on the state of the endpoint--that is, simply because these are default values does not guarantee a completely successful negotiation. When the function returns, the resulting values are returned, option by option, in the buffer pointed to by the ret->opt.buf field.

• To retrieve an endpoint's default option values, call the OTOptionManagement function, specifying T_DEFAULT for the req->flags field. You must also specify the name of the option (but not its value) in the TOption structure that you create for each of the options you are interested in.

  When the function returns, it passes the default values for the options back to you in the buffer pointed to by the ret->opt.buf field. For each option, the status field contains T_NOTSUPPORT if the protocol does not support the option, T_READONLY if the option is read-only, and T_SUCCESS in all other cases. The overall result of the request is returned in the ret->flags field. The meaning of this result is described by the status codes enumeration (page 5-29).

  When getting an endpoint's default option values, you can specify T_ALLOPT for the option name. This returns all supported options for the specified level with their default values. In this case, you must set the opt.maxlen field to the maximum size required to hold an endpoint's option information. The info.opt field of the TEndpointInfo structure specifies the maximum size of a buffer used to hold option information for an endpoint.

• To retrieve an endpoint's current option values, call the OTOptionManagement function, specifying T_CURRENT for the req->flags field. For each option in the buffer referenced by the req->opt.buf field, specify the name of the option you are interested in. The function ignores any option values
  you specify.

  When the function returns, it passes the current values for the options back to you in the buffer referenced by the ret->opt.buf field. For each option, the status field contains T_NOTSUPPORT if the protocol does not support the option, T_READONLY if the option is read-only, and T_SUCCESS in all other cases. The overall result of the request is returned in the ret->flags field. The meaning of this result is described by the status codes enumeration (page 5-29).

  When retrieving an endpoint's current option values, you can specify T_ALLOPT for the option name. The function returns all supported options for the specified protocol, with their current values. In this case, you must set the opt.maxlen field to the maximum size required to hold an endpoint's option information. The info.opt field of the TEndpointInfo structure specifies the maximum size of a buffer used to hold option information for an endpoint.

• To check whether an endpoint provider supports certain options or option values, you must call the OTOptionManagement function, specifying T_CHECK for the req->flags field. Checking options or their values does not change the current settings of an endpoint's options.
  • To check whether an option is supported, set the name field of the TOption structure to the option name, but do not specify an option value. When the function returns, the status field for the corresponding TOption structure in the buffer pointed to by the ret->opt.buf field is set to T_SUCCESS if the option is supported, T_NOTSUPPORT if it is not supported or needs additional client privileges, and T_READONLY if it is read-only.
  • To check whether an option value is supported, set the name field of the TOption structure to the option name, and set the value field to the value you want to check. When the function returns, the status field for the corresponding TOption structure in the buffer pointed to by the ret->opt.buf field is set as it would be if you had specified the T_NEGOTIATE flag. The overall result of the option checks is returned in the ret->flags field, which contains the single worst result of the option checks. The meaning of this result is described by the status codes enumeration (page 5-29).

SPECIAL CONSIDERATIONS

While an option management call is outstanding, any other functions that are called for the same endpoint return with a kOTStateChangeErr result.

If the endpoint is in asynchronous mode, the provider might issue the T_OPTIONMGMTCOMPLETE event before the function returns the first time.

COMPLETION EVENTS

T_OPTMGMTCOMPLETE

0x20000006

The OTOptionManagement function has completed. The cookie parameter of the notifier function points to the ret parameter.

SEE ALSO

Option information is formatted using the TOption structure (page 5-32). For additional information about the format of the options buffers, see "Specifying Option Values" (page 5-18).

For more information about the OTOpenEndpoint and OTAsyncOpenEndpoint, see the reference section of the chapter "Endpoints" in this book.

For additional information about using the T_ALLOPT option, see "Setting Default Values" (page 5-20) and "Obtaining Current and Default Values" (page 5-21).

For more information about creating the buffer referenced by the req->opt.buf field, see the description of the OTCreateOptions function, next.

For information about creating a string referenced by the ret->opt.buf field, see the description of the OTCreateOptionString function (page 5-42).