This class represents a connection to a Wiretap server on the Wiretap network. More...
Classes | |
class | HostTranslation |
This class is used to retrieve information of a host translation defined in the path translation database. More... | |
class | OsTypeTranslation |
This class is used to retrieve information of a operating system type translation defined in the path translation database. More... | |
class | TranslationGroup |
Public Member Functions | |
bool | compareVersion (bool &greaterOrEqual, int major, int minor=0, int maint=0, int build=0) const |
Utility method to verify server version. More... | |
void | disconnect () |
Force immediate disconnection with server. Calling this method is optional (disconnections are eventually performed anyway when WireTapServerHandles are destroyed). However, if client app determines there is a problem with a connection, it may call this method to ensure a fresh new connection with server is established for following queries. More... | |
bool | getDisplayName (WireTapStr &name) const |
Gets the display name of the Wiretap server. More... | |
const char * | getHostName () const |
Gets the name of the host machine on which the server is running. More... | |
bool | getHostTranslation (int index, HostTranslation &hostTranslation) |
const char * | getHostUUID () const |
Gets the UUID of the host machine on which the server is running. More... | |
const WireTapServerId & | getId () const |
const char * | getIdStr () const |
Gets a string that is an identifier for the Wiretap server. More... | |
bool | getInfo (WireTapServerInfo &info) const |
Gets an instance of WireTapServerInfo that contains the latest information about the Wiretap server. More... | |
bool | getNumHostTranslations (int &numHostTranslations) |
bool | getNumOsTypeTranslations (int &numOsTypeTranslations) |
bool | getNumTranslationGroups (int &numGroups) |
bool | getOsTypeTranslation (int idx, OsTypeTranslation &osTypeTranslation) |
bool | getProduct (WireTapStr &product) const |
Gets the name of the Wiretap server product. More... | |
bool | getProtocolVersion (int &major, int &minor) const |
Gets the version of the Wiretap protocol in use on the host machine on which the Wiretap server is running. More... | |
bool | getRootNode (WireTapNodeHandle &root) const |
Gets the root node of the Wiretap server. More... | |
bool | getStorageId (WireTapStr &storageId) const |
Gets an instance of WireTapStr that contains a persistent identifier for the storage device currently connected to the Wiretap server. More... | |
bool | getTranslationGroup (int index, TranslationGroup &group) |
bool | getVendor (WireTapStr &vendor) const |
Gets the vendor of the Wiretap server. More... | |
bool | getVersion (int &major, int &minor) const |
Gets the version of the Wiretap server. More... | |
bool | invalidateCache () |
Invalidate the server cache content. More... | |
bool | isConnected () const |
Determines if there is an active connection to the destination server. Connections are established automatically on demand when calling methods on WireTapServerhandle or WireTapNodehandle objects. More... | |
bool | isDatabase (const char *db) const |
Checks if this server hosts the specified database. More... | |
const char * | lastError () const |
Gets the error string for the last operation that failed. More... | |
bool | ping (unsigned timeoutMS=30000) const |
Pings the Wiretap server. More... | |
bool | pullStream (const char *streamId, const char *localFilePath) |
Pulls data from the server and writes it to a local file. More... | |
bool | pushStream (const char *streamId, const char *localFilePath) |
Reads a local file and pushes the data to the server as a stream. More... | |
bool | readFrame (const char *frameId, void *buffer, size_t bufferSize, const char *nextFrameId1=0, const char *nextFrameId2=0) |
Reads a frame from the Wiretap server and writes it to a buffer; should only be used if the frame ID is known but is not associated with a node handle. More... | |
bool | readFrame (const char *frameId, const void *params, size_t paramsSize, void *buffer, size_t bufferSize, const char *nextFrameId1=0, const char *nextFrameId2=0) |
bool | readStream (const char *streamId, void *buffer, size_t bufferSize, size_t itemOffset, size_t itemSizeInBytes, size_t &numItems) |
Reads chunks of a raw data stream from the server to a buffer. More... | |
bool | registerEventHandler (const WireTapNodeId &subject, WireTapNodeEvent::Handler *handler, const char *streamFormat=0, const char *metaData=0) |
Register an event handler to be called back when an event is received for a given subject. More... | |
void | stop (const char *reason=0) const |
Halts the current Wiretap operation and any pending operations on the current node. More... | |
bool | translatePath (const WireTapStr &srcPath, WireTapStr &dstPath, const char *srcHost=0, const char *dstHost=0, WireTapOS::OsType srcOS=WireTapOS::OS_UNKNOWN, WireTapOS::OsType dstOS=WireTapOS::OS_UNKNOWN) |
Translates a file path appropropriate for one host and operating system, into a path appropriate for a second host with a different or unknown operating system. More... | |
bool | translatePaths (const WireTapStrList &srcPaths, WireTapStrList &dstPaths, const char *srcHost=0, const char *dstHost=0, WireTapOS::OsType srcOS=WireTapOS::OS_UNKNOWN, WireTapOS::OsType dstOS=WireTapOS::OS_UNKNOWN) |
Translates a set of file paths appropropriate for one host and operating system, into paths appropriate for a second host with a different or unknown operating system. More... | |
bool | unregisterEventHandler (const WireTapNodeId &subject, WireTapNodeEvent::Handler *handler) |
Unregister an event handler registered on a given subject. More... | |
WireTapServerHandle (const WireTapServerId &serverId) | |
Constructs a WireTapServerHandle object using an instance of WireTapServerId. More... | |
WireTapServerHandle (const WireTapServerHandle &serverHandle) | |
Copy constructor. More... | |
bool | writeFrame (const char *frameId, const void *buffer, size_t bufferSize) |
Reads a frame from a buffer and writes it to the Wiretap server. More... | |
virtual | ~WireTapServerHandle () |
Destructor. More... | |
This class represents a connection to a Wiretap server on the Wiretap network.
In this context, "Wiretap server" means an instance of a particular Wiretap server running on a particular host. For example: an instance of the IFFFS Wiretap Server running on a host machine named "belgium".
WireTapServerHandle coordinates all exchanges between a Wiretap client and a Wiretap server. It maintains the network connection between the client and the server as long as required — for example, for the duration of a user work session.
To instantiate a WireTapServerHandle, Wiretap clients need a WireTapServerId object that contains the persistent identifier of the Wiretap server.
Wiretap clients can call WireTapServerHandle::getRootNode to obtain a handle on the root node of the WireTapServer. The WireTapNodeHandle for the root node can be used to access the rest of the nodes in the hierarchy.
All the member functions of the WireTapServerHandle class return a boolean value which is set to true on success or false on failure. If the return value is false, the reason for the failure can be obtained by calling WireTapServerHandle::lastError() which returns the error string. The string must be used immediately, or stored since it will be overwritten during the next call to any member function.
WireTapServerHandle::WireTapServerHandle | ( | const WireTapServerId & | serverId | ) |
Constructs a WireTapServerHandle object using an instance of WireTapServerId.
Wiretap clients can construct a WireTapServerId if the required information is known, or they can obtain it from WireTapServerList.
serverId | An input parameter. A WireTapServerId object that contains the persistent identifier of the Wiretap server. |
WireTapServerHandle::WireTapServerHandle | ( | const WireTapServerHandle & | serverHandle | ) |
Copy constructor.
Constructs a new WireTapServerHandle object that duplicates the content of the original.
serverHandle | An input parameter. The WiretapServerHandle object that is to be copied. |
|
virtual |
Destructor.
bool WireTapServerHandle::compareVersion | ( | bool & | greaterOrEqual, |
int | major, | ||
int | minor = 0 , |
||
int | maint = 0 , |
||
int | build = 0 |
||
) | const |
Utility method to verify server version.
greaterOrEqual | An output parameter. The method sets this boolean to indicate if the Wiretap server's version is not older than the version specified in following args. |
major,minor,maint,build | Input parameters. The version to compare against. |
void WireTapServerHandle::disconnect | ( | ) |
Force immediate disconnection with server. Calling this method is optional (disconnections are eventually performed anyway when WireTapServerHandles are destroyed). However, if client app determines there is a problem with a connection, it may call this method to ensure a fresh new connection with server is established for following queries.
bool WireTapServerHandle::getDisplayName | ( | WireTapStr & | name | ) | const |
Gets the display name of the Wiretap server.
name | An output parameter. The method fills this parameter with the display name of the Wiretap server. It may be the same as the name of the host machine on which the server is running. |
const char* WireTapServerHandle::getHostName | ( | ) | const |
Gets the name of the host machine on which the server is running.
bool WireTapServerHandle::getHostTranslation | ( | int | index, |
HostTranslation & | hostTranslation | ||
) |
[in] | index | Index of the host translation to fetch |
[out] | hostTranslation | HostTranslation class describing the translation |
const char* WireTapServerHandle::getHostUUID | ( | ) | const |
Gets the UUID of the host machine on which the server is running.
const WireTapServerId& WireTapServerHandle::getId | ( | ) | const |
const char* WireTapServerHandle::getIdStr | ( | ) | const |
Gets a string that is an identifier for the Wiretap server.
This is a convenience method for obtaining the server ID string. Equivalent to calling WireTapServerId.getId.
bool WireTapServerHandle::getInfo | ( | WireTapServerInfo & | info | ) | const |
Gets an instance of WireTapServerInfo that contains the latest information about the Wiretap server.
info | An output parameter. The method fills this parameter with an instance of WireTapServerInfo that describes the Wiretap server. |
bool WireTapServerHandle::getNumHostTranslations | ( | int & | numHostTranslations | ) |
[out] | numHostTranslations | the number of host translations defined in the database. |
bool WireTapServerHandle::getNumOsTypeTranslations | ( | int & | numOsTypeTranslations | ) |
[out] | numOsTypeTranslations | the number of type translations defined in the database. |
bool WireTapServerHandle::getNumTranslationGroups | ( | int & | numGroups | ) |
[out] | numGroups | The number of groups defined in the database. |
bool WireTapServerHandle::getOsTypeTranslation | ( | int | idx, |
OsTypeTranslation & | osTypeTranslation | ||
) |
[in] | idx | Index of the operating system translation to fetch |
[out] | osTypeTranslation | OsTypeTranslation class describing the translation |
bool WireTapServerHandle::getProduct | ( | WireTapStr & | product | ) | const |
Gets the name of the Wiretap server product.
product | An output parameter. The method fills this parameter with a WireTapStr object that contains the name of the the Wiretap server product. |
bool WireTapServerHandle::getProtocolVersion | ( | int & | major, |
int & | minor | ||
) | const |
Gets the version of the Wiretap protocol in use on the host machine on which the Wiretap server is running.
The Wiretap protocol is a network protocol used to communicate between Wiretap servers and Wiretap clients.
major | An output parameter. The method sets this parameter to the major version number of the Wiretap protocol. |
minor | An output parameter. The method sets this parameter to the minor version number of the Wiretap protocol. |
bool WireTapServerHandle::getRootNode | ( | WireTapNodeHandle & | root | ) | const |
Gets the root node of the Wiretap server.
root | An output parameter. The method fills this parameter with an instance of WiretapNodeHandle that gives access to the root node of the Wiretap server. |
bool WireTapServerHandle::getStorageId | ( | WireTapStr & | storageId | ) | const |
Gets an instance of WireTapStr that contains a persistent identifier for the storage device currently connected to the Wiretap server.
storageId | An output parameter. The method fills this parameter with an instance of WireTapStr that contains the persistent identifier of the storage device connected to the Wiretap server. This storageId is guaranteed to be unique across all Wiretap servers from all vendors. |
bool WireTapServerHandle::getTranslationGroup | ( | int | index, |
TranslationGroup & | group | ||
) |
[in] | index | Index of the translation group to fetch |
[out] | group | TranslationGroup class describing the translation group |
bool WireTapServerHandle::getVendor | ( | WireTapStr & | vendor | ) | const |
Gets the vendor of the Wiretap server.
vendor | An output parameter. The method fills this parameter with an instance of WireTapStr that contains the name of the company that sells the Wiretap server. |
bool WireTapServerHandle::getVersion | ( | int & | major, |
int & | minor | ||
) | const |
Gets the version of the Wiretap server.
major | An output parameter. The method sets this parameter to the major version number of the Wiretap server. |
minor | An output parameter. The method sets this parameter to the minor version number of the Wiretap server. |
bool WireTapServerHandle::invalidateCache | ( | ) |
Invalidate the server cache content.
bool WireTapServerHandle::isConnected | ( | ) | const |
Determines if there is an active connection to the destination server. Connections are established automatically on demand when calling methods on WireTapServerhandle or WireTapNodehandle objects.
This method is useful when the client wants to know if the server is still up (and has not been restarted) without having to ping the server.
bool WireTapServerHandle::isDatabase | ( | const char * | db | ) | const |
Checks if this server hosts the specified database.
db | Database string as would be returned from WireTapServerInfo::getDatabase() |
const char* WireTapServerHandle::lastError | ( | ) | const |
Gets the error string for the last operation that failed.
Wiretap clients can obtain this error message for any member function that returns a boolean. The strings can be localized if required. See the Wiretap Developer's Guide.
bool WireTapServerHandle::ping | ( | unsigned | timeoutMS = 30000 | ) | const |
Pings the Wiretap server.
timeoutMS | An input parameter. Timeout in milliseconds. |
bool WireTapServerHandle::pullStream | ( | const char * | streamId, |
const char * | localFilePath | ||
) |
Pulls data from the server and writes it to a local file.
This method truncates the local file. The sample program copyProject.cpp shows how to use this method as well as WireTapServerHandle.pushStream.
streamId | An input parameter. The ID of the stream to be read from the server. Can be obtained by calling getStreamId on the WireTapNodeHandle object for the node with which the stream is associated. |
localFilePath | An input parameter. The path and name of the local file to be written. |
bool WireTapServerHandle::pushStream | ( | const char * | streamId, |
const char * | localFilePath | ||
) |
Reads a local file and pushes the data to the server as a stream.
This method truncates the destination stream. The sample program copyProject.cpp shows how to use this method as well as WireTapServerHandle.pullStream.
streamId | An input parameter. The ID of the stream to be sent to the server. Can be obtained by calling getStreamId on the WireTapNodeHandle object for the node with which the stream is associated. |
localFilePath | An input parameter. The path and name of the local file to be read and converted to a stream. |
bool WireTapServerHandle::readFrame | ( | const char * | frameId, |
void * | buffer, | ||
size_t | bufferSize, | ||
const char * | nextFrameId1 = 0 , |
||
const char * | nextFrameId2 = 0 |
||
) |
Reads a frame from the Wiretap server and writes it to a buffer; should only be used if the frame ID is known but is not associated with a node handle.
Before calling this method, a Wiretap client should know the clip format that is appropriate for the frame. The buffer size can be obtained by calling WireTapClipFormat.frameBufferSize on an instance of WireTapClipFormat of the right type (for example: RGB, YUV, and so on).
frameId | An input parameter. The ID of the frame to be read. If the frameId is NULL or is an empty string, the read is skipped but the read-ahead is still performed. |
buffer | An input parameter. The buffer to which the frame will be written. This value cannot be NULL. |
bufferSize | An input parameter. The number of bytes in the the buffer to be used for the frame. |
nextFrameId1 | An input parameter. The next frame that will likely be read from the server. This parameter is a hint that allows the server to optimize performance. Set to NULL or the empty string to skip read-ahead. Up to 2 frame ID hints may be provided. |
nextFrameId2 |
WireTapServerHandle::lastError() can be called to get the error string.
bool WireTapServerHandle::readFrame | ( | const char * | frameId, |
const void * | params, | ||
size_t | paramsSize, | ||
void * | buffer, | ||
size_t | bufferSize, | ||
const char * | nextFrameId1 = 0 , |
||
const char * | nextFrameId2 = 0 |
||
) |
bool WireTapServerHandle::readStream | ( | const char * | streamId, |
void * | buffer, | ||
size_t | bufferSize, | ||
size_t | itemOffset, | ||
size_t | itemSizeInBytes, | ||
size_t & | numItems | ||
) |
Reads chunks of a raw data stream from the server to a buffer.
A stream is essentially raw data tagged with an identifier and stored under a node. A stream may be ASCII or binary.
When calling readStream, it is not necessary to know in advance how many chunks of data are in the stream. A chunk is comprised of an array of items. Each call to readStream on a given chunk will return the number of items actually read, which should only differ from the specified number at the end of the stream.
Random access is supported. The parameter itemOffset determines which chunk of data to read. itemOffset is expressed in items. It is not a byte offset.
A stream's identifier is normally exposed by the server via the node's metadata and can be obtained by calling getStreamId on the WireTapNodeHandle object for the node.
The node metadata normally also includes details about the stream, such as its length and format. Node metadata can be accessed by calling these methods on the node handle object:
streamId | An input parameter. The ID of the stream to be read. Can be obtained by calling getStreamId on the WireTapNodeHandle object for the node with which the stream is associated. |
buffer | An input parameter. The buffer to be used for reading the stream. This value cannot be NULL. |
bufferSize | An input parameter. The number of bytes in the the buffer to be used for reading the stream. For performance purposes when carrying out a bulk transfer, bufferSize should be set to at least 256KB. Reading a large amount of data a few bytes at a time is extremely taxing on the server. |
itemOffset | An input parameter. The number of the item at which to start reading the stream. |
itemSizeInBytes | An input parameter. The number of bytes in each item in the stream. This information should be in the metadata for the stream. |
numItems | An input/output parameter. The number of items to be read from the stream / the number of items actually read. |
bool WireTapServerHandle::registerEventHandler | ( | const WireTapNodeId & | subject, |
WireTapNodeEvent::Handler * | handler, | ||
const char * | streamFormat = 0 , |
||
const char * | metaData = 0 |
||
) |
Register an event handler to be called back when an event is received for a given subject.
[in] | subject | Subject to monitor event on. |
[in] | handler | Handler object that will be called upon events reception. |
[in] | streamFormat | An input parameter describing the format of the metadata parameter |
[in] | metaData | An optional parameter describing server- specific event parameters |
void WireTapServerHandle::stop | ( | const char * | reason = 0 | ) | const |
Halts the current Wiretap operation and any pending operations on the current node.
This method is useful when the current operation is taking too long and the user wishes to abort the operation. This method is designed to be called from a separate thread and requires that the WireTapNodeHandle still exists.
reason | This optional parameter can be to specify the 'error' to be set on the server handle. |
bool WireTapServerHandle::translatePath | ( | const WireTapStr & | srcPath, |
WireTapStr & | dstPath, | ||
const char * | srcHost = 0 , |
||
const char * | dstHost = 0 , |
||
WireTapOS::OsType | srcOS = WireTapOS::OS_UNKNOWN , |
||
WireTapOS::OsType | dstOS = WireTapOS::OS_UNKNOWN |
||
) |
Translates a file path appropropriate for one host and operating system, into a path appropriate for a second host with a different or unknown operating system.
Wiretap servers can translate network paths to account for mount-point differences between hosts and operating systems. For example, a path mounted on a UNIX system as "/CXFS/clip/f.dpx" may be mounted as "N:\myclips\f.dpx" on an NT system.
srcPath | An input parameter. A WireTapStr object containing the source path to be translated. |
dstPath | An input/output parameter. A WireTapStr object containing the destination path, the result of the translation. The source and destination path may point to the same object. |
srcHost | An input parameter. The name or IP address of the host machine on which the source paths are located. By default, this is set to the Wiretap server host (the value that would be returned by WireTapServerHandle.getDisplayName). |
dstHost | An output parameter. The name or IP address of the host machine on which the destination paths are located. |
srcOS | An input/output parameter. A constant that describes the operating system of the source machine. The constants are defined in WireTapOS::OsType. |
dstOS | An input/output parameter. A constant that describes the operating system of the destination machine. The constants are defined in WireTapOS::OsType. |
bool WireTapServerHandle::translatePaths | ( | const WireTapStrList & | srcPaths, |
WireTapStrList & | dstPaths, | ||
const char * | srcHost = 0 , |
||
const char * | dstHost = 0 , |
||
WireTapOS::OsType | srcOS = WireTapOS::OS_UNKNOWN , |
||
WireTapOS::OsType | dstOS = WireTapOS::OS_UNKNOWN |
||
) |
Translates a set of file paths appropropriate for one host and operating system, into paths appropriate for a second host with a different or unknown operating system.
Wiretap servers can translate network paths to account for mount-point differences between hosts and operating systems. For example, a path mounted on a unix system as "/CXFS/clip/f.dpx" may be mounted as "N:\myclips\f.dpx" on an NT system.
srcPaths | An input parameter. A WireTapStrList object. |
dstPaths | An output parameter. A WireTapStrList object that points to an array of destination paths. The source and destination paths may be the same object. |
srcHost | An input parameter. The name or IP address of the host machine on which the source paths are located. By default, this is set to the Wiretap server host (the value that would be returned by WireTapServerHandle.getDisplayName). |
dstHost | An input parameter. The name or IP address of the host machine on which the paths are to be accessed. By default, this is set to the local hostname. |
srcOS | An input/output parameter. A constant that describes the operating system of the source machine. The constants are defined in WireTapOS::OsType. By default, this is set to WireTapOS::OS_UNKNOWN. |
dstOS | An input/output parameter. A constant that describes the operating system of the destination machine. The constants are defined in WireTapOS::OsType. By default, this is set to WireTapOS::OS_UNKNOWN. |
bool WireTapServerHandle::unregisterEventHandler | ( | const WireTapNodeId & | subject, |
WireTapNodeEvent::Handler * | handler | ||
) |
Unregister an event handler registered on a given subject.
[in] | subject | Subject that was monitored. |
[in] | handler | Handler object associated to the subject. |
bool WireTapServerHandle::writeFrame | ( | const char * | frameId, |
const void * | buffer, | ||
size_t | bufferSize | ||
) |
Reads a frame from a buffer and writes it to the Wiretap server.
Before calling this method, a Wiretap client should know the clip format that is appropriate for the frame. The buffer size can be obtained by calling WireTapClipFormat.frameBufferSize on an instance of WireTapClipFormat of the right type (for example: RGB, YUV, and so on).
frameId | An input parameter. The ID of the frame to be written. |
buffer | An input parameter. The buffer that contains the frame data. This value cannot be NULL. |
bufferSize | An input parameter. The number of bytes in the the buffer. |