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

Appendix D - XTI Option Summary

Options Negotiation Rules

This section describes the rules governing option negotiation and the error conditions that might occur during this process. Unless stated otherwise, these rules apply to all functions that allow you to specify option values.

A basic rule to keep in mind is that options change only as the result of successful negotiations or partly successful negotiations. If you use any function except the OTOptionManagement function, the changes last for the duration of that function invocation. Option values are not changed by a change in the state of an endpoint. Once you change an option value permanently, there is no function that you can call to restore an option to its previous value, unless that previous value is the default value.

Negotiating Multiple Options

You can use one function to negotiate several options by placing the options in the options buffer passed to the function. If one of the options is ignored or rejected for any reason, the outcome depends on the function you use to set options.

• If you use the OTOptionManagement function, the function returns the result of negotiating each option in the status field of each option. The failure of one or more options does not cause the function to fail.

• The OTConnect, OTAccept, OTSndUdata, or OTSndURequest functions might succeed or fail, depending on the implementation and on the error condition. Options that are not supported are generally ignored; they do not cause a function to fail or a connection to abort. However, if the endpoint provider is unable to negotiate options that are absolute requirements or options that are read-only, these functions will fail.

  If option negotiation causes one of these functions to fail, it is possible that some options were successfully negotiated before the failure. However, it is not possible to determine which of the options caused the failure. Those options that were successfully negotiated retain their new values. There is no undo mechanism.

If you specify the same option more than once, the endpoint provider does not check for duplicate occurrences of the same option. It simply processes the options one after another. However, the endpoint provider might negotiate options in any order; therefore, it is not safe to make any assumptions that a later occurrence of an option will override an earlier occurrence.

Initiating an Option Negotiation

You initiate an option negotiation by calling the OTOptionManagement function with the flag T_NEGOTIATE set or by calling the OTConnect, OTSndUData, or OTSndURequest function and specifying an options buffer length that is greater than 0. You can specify values for some or all of the options supported by an endpoint. The endpoint provider takes values for options that you do not specify explicitly in the options buffer from the endpoint's internal options buffer. This buffer contains the endpoint's current option values; these could be default values, values that you specified when you configured the provider, or values resulting from a previous negotiation.

If the endpoint supports an option, the possible outcome of option negotiation depends on whether the option is an absolute requirement, as described in the next two sections. If the endpoint does not support the option, the OTOptionManagement function reports T_NOTSUPPORT in the status field. The OTConnect, OTSndUData, or OTSndURequest functions ignore the option.

Options That Are Absolute Requirements

If the option is an absolute requirement, the result of the negotiation depends on whether the negotiated value is the same as the requested value. If it is, the status field in the TOption structure describing the option is set to T_SUCCESS when the function returns. If the negotiated value is not the same as the requested value, the result depends on the function used to negotiate the option:

• The OTOptionManagement function returns successfully, but the returned option has its status field set to T_FAILURE.

• A call to the OTConnect function fails. If the call is synchronous, the function returns with the kOTLookErr result. If the call is asynchronous, the endpoint provider issues a T_DISCONNECT event to let you know that the connection has been rejected.

• The OTSndUData function fails with the kOTLookErr result; or if it returns successfully, the endpoint provider issues a T_UDERR event to indicate that the datagram was not sent.

Options That Are Not Absolute Requirements

If the requested option is not an absolute requirement, the result of the negotiation depends on whether the negotiated value is the same as the requested value. If it is, the endpoint provider sets the status field of the TOption structure describing the option to T_SUCCESS. If the negotiated value is different than the proposed value, the endpoint provider sets the status field of the TOption structure describing the options to T_PARTSUCCESS. If the option is not supported, the status field is set to T_NOTSUPPORT.

Conflicting Option Values

It is possible that a requested option value conflicts with the value of another option that is proposed with the same call to the function or with a value that is currently set. The endpoint provider might not detect these conflicts immediately, and later they might lead to unpredictable results. If the endpoint provider detects conflicts at negotiation time, the conflicts are resolved according to the rules stated above.

An endpoint provider usually detects conflicts at the time it establishes a connection or sends a datagram. Consequently, if you use the OTOptionManagement function to set options, you might not become aware that there is a problem due to conflicting options until the options are actually exercised during connection establishment or data transmission.

Privileged or Read-Only Options

A protocol implementation can define options to be privileged or read-only. These two categories are not necessarily separate. A privileged option might be inaccessible or read-only for nonprivileged clients. An option might be read-only for all clients or solely for nonprivileged clients. Here are two general guidelines to keep in mind:

• A client must be privileged to be able to change a privileged option.

  In the Mac OS implementation of Open Transport, there are no privileged options.

• A client cannot usually change the value of a read-only option.

  An option might be read-only in some endpoint states but not in others. For example, the ISO quality-of-service options are negotiable in the T_IDLE and T_INCON states, and read-only in all other states except T_UNINIT. Consult the documentation provided for the protocol you are using to determine whether an endpoint's state affects the status of read-only options.

If you request negotiation of a privileged option using the OTOptionManagement function, the function returns successfully with the status field of the privileged option set to T_NOTSUPPORT. If you use the OTConnect, OTAccept, OTSndUData, or OTSndURequest functions, the option is ignored--that is, the function result is not affected by the fact that the options are not supported.

If you request negotiation of a read-only option using the OTOptionManagement function, the function returns with the status field of the read-only option set to T_READONLY. If you use any other function to change a read-only option, the results vary with the function used:

• The OTAccept or OTConnect functions fail with the kOTAccessErr result, or the connection establishment aborts and the endpoint provider issues a T_DISCONNECT event. If the connection aborts, a synchronous call to OTConnect fails with the KOTLookErr result. Timing and the protocol implementation determine whether the OTAccept function succeeds or fails with the kOTLookErr result.

• The OTSndUData function might return the kOTLookErr result or return successfully, but the endpoint provider issues a T_UDERR event to indicate that it did not send the datagram.

Error Conditions

Option negotiation might be affected if you try to negotiate an illegal option, a privileged or read-only option, an unsupported option, or an option for an unsupported protocol (level). The results of attempting to negotiate privileged or read-only options are described in "Privileged or Read-Only Options". This section explains the outcome of negotiating illegal options and describes other problems that might arise during option negotiation.

An option is illegal in these cases:

• It is the last option in an options buffer, and the length specified in the TOption.len field exceeds the remaining size of the options buffer. (The length of the option includes the option header as well as the option value. See Figure 7-2 for information about the format of option information in an options buffer.)

• The option value does not fall within the range of legal values for the option. The range of option values that are valid for a protocol implementation are given in the documentation provided for the protocol.

If you specify an illegal option, the following error conditions result, depending on the function you used:

• The OTOptionManagement function returns with the kOTBadOptionErr result.

• Either the OTAccept or OTConnect function fails with a kOTBadOptionErr result, or the connection establishment aborts, depending upon the implementation and the time the illegal option is detected. If the connection aborts, the endpoint provider issues a T_DISCONNECT event. If OTConnect is executing synchronously, it fails with the kOTLookErr result. The OTAccept function either succeeds, or fails with the kOTLookErr result, depending on the implementation.

• The OTSndUData function fails with the kOTBadOptionErr result, or it returns successfully, but the endpoint provider issues a T_UDERR event to indicate that it did not sent the datagram.

If the options buffer you pass to a function contains multiple options and one of them is illegal, the function fails as described. However, if you used the OTOptionManagement function to set options, it is possible that some or all of the legal options in the buffer were successfully negotiated. You can check the current status for the endpoint by calling the OTOptionManagement function with the T_CURRENT flag set.

The OTOptionManagement function fails with the kOTBadOptionErr result if you specify an unknown value for the option protocol level. Using any other function to specify an unknown option level does not cause the function to fail, but results in the option being ignored.

Specifying an option name that is unknown or unsupported by the endpoint does not cause a function to fail. The OTOptionManagement function returns T_NOTSUPPORT in the status field for the option; the other endpoint functions ignore the unknown options.

Allowing the Endpoint Provider to Select an Option Value

You can specify that an endpoint provider selects an appropriate option value by setting the endpoint's value field to the constant T_UNSPEC. This is especially useful in complex options such as ISO throughput where the option value has an internal structure.

---

Subtopics

Negotiating Multiple Options

Initiating an Option Negotiation

Options That Are Absolute Requirements

Options That Are Not Absolute Requirements

Conflicting Option Values

Privileged or Read-Only Options

Error Conditions

Allowing the Endpoint Provider to Select an Option Value