HIOOpen

Syntax

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

HIOHandle HIOOpen(const char            *hioName,
                  HIOConnectionCallback  connection,
                  void                  *context,
                  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.
connection Callback to be invoked when the first host PC application connects and the last application disconnects.
context Pointer to user-specified local storage.
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.

Applications should prefer the HIOOpenEx function as it provides more flexibility for asynchronous callbacks. This function is provided for compatibility.

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 connection will be called with the status HIO_STATUS_NEW_CONNECTION when the first PC application registers with the channel hioName. The callback connection 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 connection.

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
HIOOpenEx
HIOClose

Revision History

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


CONFIDENTIAL