Legacy Document

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

Chapter 25 - 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

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

C++ INTERFACE

OSStatus 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, which describes the action to be taken by the function and the options affected.

ret

A pointer to an e option management structur, which describes the options that were changed or returned by the function and how successful the negotiation process was.

function result

See Discussion.

DISCUSSION

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 synchronous mode, the endpoint will returns results of the option managment in the structure referenced by the req parameter. If the endpoint is in asynchronous mode, the function returns immediately with the kOTNoError result. When the operation completes, the endpoint calls your notifier with the T_OPTNMGMTCOMPLETE event code. The cookie parameter to the notifier will contain the value of the ret parameter. If you have not installed a notifier function, it is not possible to determine when the function completes. For more information on notifier functions and event codes see "Using Notifier Functions" and "Event Codes".

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 .

  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. (The option buffer should have an option header, but no value fields; the TOption.len field should be set to kOTOptionHeaderSize.)

  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.

  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, which you can get from the info.opt field of the TEndpointInfo structure.

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

  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, which you can get from the info.opt field of the TEndpointInfo structure.

• 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. (The option buffer should have an option header, but no value fields; the TOption.len field should be set to kOTOptionHeaderSize.) 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 request for option negotiation is returned in the ret->flags field. The meaning of this result is described by the status codes enumeration.

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_OPTMGMTCOMPLETE event before the function returns the first time.

SEE ALSO

The format of option buffers in "Specifying Option Values".

The OTCreateOptions function.

The OTCreateOptionString function.