#include <cafe.h> #include <cafe/hio.h> HIOHandle HIOOpen(const char *hioName, HIOConnectionCallback connection, void *context, HIOChannelOptions options, HIOChannelFlags flags);
|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:
|flags||Reserved for future use.|
||The handle to the open Host I/O channel|
||The channel could not be opened, most likely due to having reached the open channel limit.|
||The Host I/O channel could not be opened.|
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.
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.
|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.|
2013-05-08 Automated cleanup pass.
2011-11-04 Updated return values.
2011-02-21 Initial version.