Legacy Document

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

Chapter 21 - Providers Reference / Functions

Sending Module-Specific Commands /

OTIoctl

Sends a module-specific command to an Open Transport protocol module.

C INTERFACE

SInt32 OTIoctl(ProviderRef ref, UInt32 cmd, void* data);

C++ INTERFACE

SInt32 TProvider::Ioctl(UInt32 cmd, void* data);

PARAMETERS

ref

The provider reference of the provider affected by the specified command.

cmd

A routine selector for the module-specific command.

data

Data to be used by the module-specific command or a pointer to such data. The interpretation of the data parameter is command specific.

function result

See Discussion.

DISCUSSION

The OTIoctl function sends a module-specific command to an Open Transport protocol module.

If the provider is in synchronous mode, the function waits until the command completes. It then returns 0 or a positive integer. The positive integer's meaning is defined by the Open Transport module that you are using. Refer to the documentation for that module. If the OTIoctl function fails while executing synchronously, its return value is a negative integer corresponding to an Open Transport result code.

If the provider is in asynchronous mode, it returns immediately with a return value kOTNoError or another Open Transport result code. When the function completes execution, Open Transport calls the notifier function installed for the provider, passing the event code kStreamIoctlEvent and a result parameter indicating the result of the completed OTIoctl function. If the value of the result parameter is greater than 0, the corresponding result code is defined by the command; otherwise, the value of the result parameter corresponds to an Open Transport result code.

IMPORTANT

You can have only one oustanding call to the OTIoctl function at any one time.

COMPLETION EVENT CODES

kStreamIoctlEvent

SPECIAL CONSIDERATIONS

Using the OTIoctl function makes your application module dependent; you should not use the OTIoctl function if you want your application to be transport independent.