Generated: Mon, 27 Jul 2020 18:57:13 EDT
class Standard . IOobject {int32 deleteOnClose;int32 ioID;int32 selectFlags;} inherits from Object;
The IOobject class is the base class for all I/O objects. Because it can handle multiple transport schemes, derived classes that implement specialized functionality are uncommon.
IOobject:create(any name)
See initialize.
IOobject:initialize(any name)
The initialize method takes a single argument that indicates the transport mechanism, address and desired operation.
The underlying Id for the descriptor is returned; it will be set to -1 if an error has occurred.
IOobject:getID()
The getID method returns the Id of the underlying I/O descriptor for this object and is intended to indicate whether or not the IOobject was successfully initialized. If the object was not successfully created, -1 is returned. Any value other than -1 is intended to indicate a successfully opened I/O service.
IOobject:getDescriptor()
The getDescriptor method returns the underlying file descriptor/handle for the IOobject. If the object was not successfully created or the underlying I/O service does not make use of a file description, -1 is returned.
IOobject:setDeleteOnClose()
The setDeleteOnClose method sets a delete-on-close flag, which will cause the IOobject to be automatically deleted (it sends itself a deleteYourself message) when all associated descriptors are closed. By default, the flag is not set. Once the delete-on-close flag has been set by setDeleteOnClose, it can be cleared by the clearDeleteOnClose method. This is most commonly used when handing an IOobject off to another application that will not delete an object that it did not create. The class SendFile, which attempts to perform optimal copying of data between two opened IOobject objects, is an excellent example of such an application.
The constant value 0 is returned.
IOobject:clearDeleteOnClose()
The clearDeleteOnClose method is the inverse of the method setDeleteOnClose. It clears the delete-on-close flag. If an end-of-file condition is reached, the IOobject object will not automatically delete itself.
The constant value 0 is returned.
IOobject:open(string name)
The open method is identical in behavior to the initialize method, with the exception that it will close any existing I/O association.
IOobject:readBytes(optional int32 bytesToRead, optional int32 bfrSize)
Data is retrieved from a stream using the readBytes method. The number of desired bytes of data is passed as the first argument, bytesToRead. If bytesToRead is set to -1 or nil, the read will return all data available up to some reasonable buffer size (the exact size can be obtained by retrieving the system information attribute IOmaxReadBuffer).
In some situations, the exact amount of the data to be read is known to an application ahead of time. As an example, consider a file whose length was obtained using the getFileInfo() function or an interprocess message prefixed with a length. Rather than performing a read into an internal buffer and then copy the result to a string, the data can be read directly into the result string if the optional argument bfrSize is set to the correct size.
If fromObject is nil, this method will return no value; otherwise:
IOobject:seekToOffset(int32 offset)
For some media, such as files, the position pointer associated with the open descriptor can be altered using seekToOffset.
IOobject:seekThenRead(int32 offset, int32 bytesToRead, optional int32 bfrSize)
The seekThenRead method is a combination of seekToOffset and readBytes. A seek is performed to offset and then number of bytes indicated by bytesToRead is retrieved.
IOobject:writeBytes(string dataToSend)
The writeBytes method outputs the contents of a string to an I/O stream. A more powerful facility is provided by writeVectorOfBytes.
If fromObject is not nil, then the number of bytes written to the stream is returned. If the buffer fills up in the process of writing data to the output stream, this routine will wait for it to drain so that the I/O operation can proceeed, thus partial writes are an indication that an error was encountered.
IOobject:writeVectorOfBytes(int32 skipOffset, string data1, optional string data2)
The writeVectorOfBytes method implements a powerful I/O primitive that minimizes the number of bytes of data that must be copied in order to perform an I/O operation. It takes a minimum of two arguments:
Logically, the data to be sent is formed by concatenating all of the strings and then deleting the initial number of bytes indicated by skipOffset. The underlying implementation performs no actual concatenation nor modification of the source strings, so the data is copied only once from the address space of the FARGOS/VISTA Object Management Environment process into the kernel.
If fromObject is not nil, then the number of bytes written to the stream is returned. If the buffer fills up in the process of writing data to the output stream, this routine will wait for it to drain so that the I/O operation can proceeed, thus partial writes are an indication that an error was encountered. While waiting for the kernel's I/O buffer to drain, all other threads within the FARGOS/VISTA Object Management Environment will continue execution.
IOobject:sendDatagram(string dataToSend, string destination)
The sendDatagram method sends a datagram, whose contents are specified by the string dataToSend, to another communications port, whose address is specified in destination. The IOobject must have been created using a datagram-based protocol. The most common such protocol is the User Datagram Protocol (UDP) of the TCP/IP version 4 protocol suite. Other transport schemes that use datagrams include:
If fromObject is not nil, then the number of bytes written when sending the datagram is returned. Normally, this is the same as length(dataToSend), but it may be -1 if an error was detected locally. Many datagram-based protocols are unreliablea by design, such successfully sending a datagram does not usually carry with it an assurance that it was received by the target destination.
IOobject:receiveDatagram(any maxBytes)
The receiveDatagram method receives a datagram that was sent to the communications port represented by the IOobject. The IOobject must have been created using a datagram-based protocol. The most common such protocol is the User Datagram Protocol (UDP) in the TCP/IP protocol suite. The corresponding method sendDatagram is used to send datagrams.
If a datagram is successfully received, a two-element array is returned. The first element of the array (subscript 0) contains a string that holds the contents of the datagram. The second element of the array holds a string that identifies the transport address of the sender, which is in a format identical to that returned by getLocalAddress and getPeerAddress. The selectForRead or waitUntilReadyForRead methods can be used to ensure that a datagram is available prior to invoking receiveDatagram.
IOobject:selectForRead(optional oid clientObj)
An object can request to be notified when there is data available for reading using the selectForRead method. Normally the object to be notified is implied as being the fromObject, but the selectForRead method takes an optional argument that permits the specification of an alternate client. The client object is sent a canRead message and passed the object Id of the IOobject.
This method does not return a value.
IOobject:waitUntilReadyForRead()
The waitUntilReadyForRead method can be used to block the progress of a thread until data is available. It is intended to be used by an RPC-style method invocation, thus a value is returned only when data is available for reading.
An integer value indicating the pending status of any other selectForRead or selectForWrite operations is returned. Typically, the value will be zero, but a simultaneous selectForWrite might be on-going, in which case the return value will be 2.
IOobject:selectForWrite(oid clientObj)
The selectForWrite method is identical to selectForRead, except that it sends a canWrite message (instead of canRead) when it is possible to write more data on the IOobject.
IOobject:waitUntilReadyForWrite()
The waitUntilReadyForWrite method is identical to waitUntilReadyForRead, except that it returns a value when it is possible to write more data on the IOobject.
An integer value indicating the pending status of any other selectForRead or selectForWrite operations is returned. Typically, the value will be zero, but a simultaneous selectForRead might be on-going, in which case the return value will be 1.
IOobject:acceptConnection(assoc acl)
New connections can be accepted from an IOobject that is in a listen state by using the acceptConnection method. It takes a single argument, which is an access control list to be set for the new IOobject that is associated with the accepted connection.
IOobject:closeForRead()
Some connections are bi-directional and closeForRead permits one end of the connection to be closed. No further reads will be possible. If the delete-on-close flag is set (see setDeleteOnClose), the object will automatically be deleted.
IOobject:closeForWrite()
Some connections are bi-directional and closeForWrite permits one end of the connection to be closed. No further writes will be possible.
IOobject:getLocalAddress()
The getLocalAddress method returns the transport address associated with the IOobject. This method is supported for all instances of IOobject, including files.
IOobject:getPeerAddress()
The getPeerAddress method returns the transport address of the endpoint associated with the IOobject. While this method can be invoked on any IOobject, a useful return value is obtained only for connected streams.