HIOOpenEx

Syntax

#include <cafe.h>
#include <cafe/hio.h>

HIOHandle HIOOpenEx(const char        *hioName,
                    HIOAsyncStruct    *asyncStruct,
                    HIOChannelOptions  options,
                    HIOChannelFlags    flags);

Parameters

hioName Unique NULL-terminated string name to be associated with the requested Host IO channel. Must match the name used by the corresponding host PC application that will communicate on this channel. Must be limited to 15 characters.
asyncStruct This parameter contains the callback function that should be called to receive information about PC clients listening to this channel. This callback will be called when the first application connects and the last application disconnects. This parameter also contains a message queue to be used by HostIO to process events for this channel.
options Specifies read/write properties of the requested channel:

HIO_CHANNEL_OPTION_READ
HIO_CHANNEL_OPTION_WRITE
HIO_CHANNEL_OPTION_READ_WRITE

flags Reserved for future use.

Return Values

>= 0 The handle to the open Host I/O channel
HIO_STATUS_INVALID_CHANNEL The channel could not be opened, most likely due to having reached the open channel limit.
< 0 The Host I/O channel could not be opened.

Description

Acquires a Host I/O channel and returns its handle.

This function will fail if a channel is unavailable or if resources are otherwise unavailable to establish a connection. This function will also fail if the host IO facility has not been initialized.

The callback in asyncStruct will be called with the status HIO_STATUS_NEW_CONNECTION when the first PC application registers with the channel hioName. The callback in asyncStruct will also be called with the status HIO_STATUS_NO_CONNECTIONS when the last PC application unregisters from this channel. This mechanism can be used by the program to avoid sending data to the PC if there are no PC applications waiting for data.

HIO_STATUS_NEW_CONNECTION and HIO_STATUS_NO_CONNECTIONS are used exclusively with the callback in asyncStruct.

Multiple host PC applications can register with the same channel (via the hioName); the Host IO server will broadcast messages to each registered application. However, no protocol is implemented to manage communications between the target and multiple host PC applications. Such mechanisms are left as an exercise for the user.

Host I/O is available on development systems only.

Do Not Call From

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.
Production code Do not call this function in production code. It is available only for debugging purposes.

See Also

HIOInit
HIOOpen
HIOClose

Revision History

2013-05-08 Automated cleanup pass.
2011-11-04 Updated return values.
2011-02-21 Initial version.


CONFIDENTIAL