Class IOPort
#include <IOPort.h >
Access a MAE I/O resource.
This class is designed to be very close to standard I/O routines to make migratation as easy as possible.
The fundamental difference is that IOPort does not directly access the file system; it accesses named MAE resources. See tioreg for managing these resources. The IoGW daemon handles these I/O requests. IOPort talks to to IoGW via the IoAPI class.
Note that IOPort can be a substitute for FILE*. An instance of IOPort does not contain the vitals like file position, so it is save to make copies of IOPort - like you would a FILE*.
const string& resourceName |
resource name to connect to; the resource name may be a filename for the MAE filesystem or a unique keyword for . Default value: "" |
Constructor - connect to a named resource.
Use active() to verify connection to resource was successful.
const string& resourceName |
resource name to connect to |
const string& mode |
existing resources already know if they are readable/writable, but when accessing/creating new resources in directory resources, specify the mode Default value: "" |
Connect/Open the named resource. Analogous to fopen().
Return value: true upon success, false upon failure
Determine if this port connection is valid.
A valid port has a resource name.
This does not reflect whether the connection is open or active; see active().
Return value: true if valid, false if not
Determine if this port is open and working.
If EOF or there's an error, the port is not considered active.
Return value: true if port is actrive, false if not
Determine if we are I/O operation blocked
Return value: true if blocked, false if not
Determine if end-of-file has occurred.
Return value: true on EOF, false if not
Query the error code of the last I/O operation.
Return value: see errno.h
Query the error message of the last I/O operation.
Return value: see errno.h
Return the name of the MAE I/O resource.
Return value: name of resource, null string if not valid
Determine if a character is ready to read on input (so a blocking getchar() is safe).
Return value: true if a character is ready, false if not
bool blocking |
true to wait for a character, false if no wait Default value: true |
Get/Receive a character from the port. Analogous to fgetc().
Return value: the character receive, EOF if end-of-file, or 0 if no character ready
bool blocking |
true to wait for text, false if no wait Default value: true |
Get/Receive a line of text (blocking) up to \n from the port. Analogous to fgets().
The \n is included in the returned string.
Return value: the text line received, null string on end-of-file
RawData& rawdata |
(output) where the inbound data will be stored |
size_t size |
size of record to read (in bytes) |
size_t nmemb |
number of records to read Default value: 1 |
bool blocking |
true to wait for text, false if no wait Default value: true |
Read a number of records of binary data from the port. Analogous to fread().
The result should have size*nmemb characgters in it; if less,
then less data was available than requested.
Return value: number of records read; null string on EOF
int c |
the character to un-read |
Un-read a character read from input.
Return value: c upon success, EOF on failure
Determine if we can write a character to the port.
Return value: true if writable, false if not
int c |
the character to send |
Send a character to the port. Analogous to fputc().
Return value: c upon success, EOF on failure
const string& text |
the text to send |
Send text to the port. Analogous to fputs().
Return value: 0+ on success, EOF on failure
const RawData& rawdata |
the data to send |
Send binary data to the port. Analogous to fwrite().
Return value: 0+ on success, EOF on failure
Return the position in the file - number of bytes read/written. Analogous to ftell().
Return value: file position (none is 0)
long offset |
the new file pointer position |
Move the file pointer to a specified point in the file from the start of the file. Analogous to fseek().
Note that this has no effect on resources that stream data, only on files.
Return value: 0 upon success, EOF on failure
Move the file pointer to the beginning of the file. Analogous to rewind().
Note that this has no effect on resources that stream data, only on files.
bool exclusive |
Flag: true if nothing else allowed to read or write to this resource, false if other apps can read this resource |
bool wait |
Flag: true if app should wait until the lock has been released - this will block the app Default value: true |
Attempt to lock access to this file resource.
If an exclusive lock has already been obtained, then it can be switched to shared.
Return value: true if the lock was acquired, false if it was not acquired
Release a lock from this resource/file. Other resources will be allowed to read or write once unlocked.
Close this port, stopping any further reads or writes.
Return value: 0 upon success, EOF on failure
Close all open connections
const string& pathname |
must be a MAE virtual filesystem pathname (file or directory) |
MaeStat& statbuf |
(output) a structure to contain the various details about the pathname |
Equivalent to stat() in Standard C Library, get statistics about the pathname provided.
Return value: errno for the operation: 0 upon success ENOENT if file does not exist
const string& path |
the directory from which to get filename |
bool includeDirs |
= Flag: include directory names Default value: true |
bool includeFiles |
= Flag: include filenames Default value: true |
Get filename and/or directory name entries in the MAE virtual file system directory provided.
Use this instead of opendir()/readdir()/closedir().
Return value: list of filenames
const string& request |
the request keyword in question |
Determine if a MAE message is an IOPort message from iogw.
Use this call in your .mreg with #msgvalid file to check if you should IOPort::handleMessage().
This call is valid for any/all port connection(s).
Return value: true if request is a for IOPOrt from iogw
const string& request |
the request keyword in question |
const XMLData& param |
parameters with data associated with request |
Handle a MAE message from iogw.
This call is valid for any/all port connection(s).
Return value: true if processed successfully, false on error or invalid request
Clear any receive input callbacks already setup.
IOPortDataCB cbfn |
the callback function to call |
void* cbdata |
(optional) some data to pass to the callback function |
Setup a receive input callback for whenever an input character is received.
This will also be called when EOF is reached.
IOPortDataCB cbfn |
the callback function to call |
void* cbdata |
(optional) some data to pass to the callback function |
Setup a receive input callback for whenever an input line is received.
A line is terminated by \n, which must be prevent before cbfn is called.
This will also be called when EOF is reached.
IOPortDataCB cbfn |
the callback function to call |
void* cbdata |
(optional) some data to pass to the callback function |
Setup a receive input callback for whenever an input file is received.
The entire contents of the file has been received.
string name |
Name of the resource of this port |
static vector <IOPortData > mbuf |
The IOPort buffers. Only one buffer per resource within the program. |
const string& name |
name of resource to find its buffer |
bool create |
Default value: false |
Return the mbuf for the named resource
Return value: an IOPortData buffer, which has eof set if invalid
const string& name |
name of resource to remove its buffer |
Remove an I/O buffer
const string& response |
block until this response - open, input, tell |
Block until we get a response from iogw
Return value: true if response received, false if something happened (like eof)
const IOPortData& data |
the buffer to service |
When new input or EOF is received, this method is called to notify the
app if any callbacks were setup.