Legacy Document

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

Chapter 21 - Providers Reference / Functions

Controlling a Provider's Modes of Operation /

OTAckSends

Specifies that a provider not make an internal copy of data being sent.

C INTERFACE

OSStatus OTAckSends(ProviderRef ref);

C++ INTERFACE

OSStatus TProvider::AckSends();

PARAMETERS

ref

The provider reference of the provider that is sending data.

function result

An error code. See Appendix B for more information.

DISCUSSION

By default, providers make an internal copy of data before sending it and they do not acknowledge sends. If you use the OTAckSends function to specify that the provider acknowledge sends and you call a function that sends data, the provider does not copy the data before sending it. Instead, it reads data directly from your buffer while sending. For this reason, you must not change the contents of your buffer until the provider is no longer using it. The provider lets you know that it has finished using the buffer by calling your notifier function and passing the T_MEMORYRELEASED event code for the code parameter, a pointer to the buffer that was sent in the cookie parameter, and the size of the buffer in the result parameter. The T_MEMORYRELEASED event is not serialized with other notification events and will re-enter your notifier function.

If you have not installed a notifier function for the provider, this function returns the kOTAccessErr result. If a send is currently outstanding on the provider, from a call to the OTSnd, OTSndUData, OTSndUReply, OTSndURequest, OTSndReply, or OTSndRequest functions, the OTAckSends function returns a kOTChangeStateErr message.

Although you must wait for a T_MEMORYRELEASED event before you touch the buffer containing the data being sent, you do not have to wait for a T_MEMORYRELEASED event to send more data. You can continue to process data normally, sending data until you get a flow error and then resuming sends when you receive the T_GODATA event.

WARNING

You need to be sure there are no outstanding T_MEMORYRELEASED events for a provider before you close the provider. Otherwise, Open Transport attempts to deliver the event to a provider that no longer exists, with unpredictable results, such as crashing the system.

To find out a provider's current send-acknowledgment mode, call the OTIsAckingSends function.

The send-acknowledgment mode of a provider is ignored by mapper providers, AppleTalk service providers, and TCP/IP service providers.

COMPLETION EVENT CODES

T_MEMORYRELEASED

SPECIAL CONSIDERATIONS

Because of the complexity of handling flow control, Open Transport performance suffers when the acknowledge sends option is used with noncontiguous data, such as when you pass an OTData structure to the OTSnd function. It is best to use this option with contiguous data or with OTData structures whose last element is large.

SEE ALSO

The OTDontAckSends function.

"Setting a Provider's Send-Acknowledgment Status".

See the chapter "Advanced Topics" for more information about acknowledging sends.