Legacy Document

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

Chapter 26 - Ports Reference / Functions

Requesting a Port to Yield Ownership /

OTYieldPortRequest

Requests that a port be yielded.

C INTERFACE

OSStatus OTYieldPortRequest(ProviderRef ref, OTPortRef port, 
                     OTClientList* buffer, size_t bufferSize); 

C++ INTERFACE

None. C++ applications use the C interface to this function.

PARAMETERS

ref

The provider reference for the provider that wants to use the port. This provider (normally an endpoint) must be open on the requested port. You cannot use this provider while the yield request is being processed.

port

The port reference for the port you wish to use.

buffer

If the request is denied, on output this contains a pointer to a client list structure, giving the names of all clients that rejected the request (normally only one). You can use a value of NULL to force the client to yield the port; this only works if the provider is passively listening on the port. Use a value of (void*)-1L to cancel the yield request.

bufferSize

The size of the buffer, including the fNumClients field in the client list structure.

function result

See Discussion.

DISCUSSION

The OTYieldPortRequest function requests the current owner of a port (normally a serial port or modem) to yield ownership of it.

Port yielding works in one of two ways. You get the first mechanism by calling OTYieldPortRequest, passing a value for buffer that points to a client list buffer. Open Transport then looks through all the clients on the system. If the client has any providers that use the port in question, Open Transport sends the client a kOTClosePortRequest event. The client either handles that request (by closing the provider), or returns an error that indicates why the request was denied. Any client that doesn't have a notifier (as set by OTRegisterAsClient) is assumed to allow the request.

If any client denies the request, the OTYieldPortRequest function fails. The function could also fail because there is not enough memory (kENOMEMErr), the port does not support yielding (kOTNotSupportedErr), the provider does not use the port, or the port does not exist (kOTBadReferenceErr), or because the client currently using the port is already connected (kENOENTErr). Otherwise, Open Transport attempts to get the port for you from the driver. If it succeeds, the port is ready for you to use. The port remains available for a driver-specified amount of time (typically about 10 seconds). If you don't bind or connect the port in that time, the port reverts back to its previous owner. If you do bind or connect to the port before the timer expires, you now own the port. When you unbind or disconnect, the port reverts back to its previous owner.

The second mechanism for port yielding comes into play when you set buffer to nil. In that case, Open Transport bypasses the check described above, and immediately attempts to grab the port. The call results depend solely on whether that succeeds or fails.

After getting a port, you have a number of choices:

1. You can open it, as described above.

2. You can decide not to open it, and ignore it. After a while, the driver will time out, and the port will revert back to the previous owner.

3. You can decide not to open it, and be a good citizen by switching the port back to the previous owner immediately. You do this by calling the function OTYieldPortRequest and passing -1 for the buffer parameter.

SPECIAL CONSIDERATIONS

On PowerPC computers, the OTYieldPortRequest function is available only to PowerPC-native clients; there is no mixed-mode glue for the function, so you must build a fat application in order to use it.

You can only use this function at system task time.

SEE ALSO

The OTRegisterAsClient function.