Wiretap API  <small>Wiretap 2020.1</small>
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
WireTapServerHandle Class Reference

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 WireTapServerIdgetId () 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...
 
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...
 

Detailed Description

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.

See Also
WireTapServerId, WireTapServerInfo, WireTapServerList, and the sample program listAllServers.cpp (which is included in the SDK).

Constructor & Destructor Documentation

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.

Parameters
serverIdAn 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.

Parameters
serverHandleAn input parameter. The WiretapServerHandle object that is to be copied.
virtual WireTapServerHandle::~WireTapServerHandle ( )
virtual

Destructor.

Member Function Documentation

bool WireTapServerHandle::compareVersion ( bool &  greaterOrEqual,
int  major,
int  minor = 0,
int  maint = 0,
int  build = 0 
) const

Utility method to verify server version.

Parameters
greaterOrEqualAn 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,buildInput parameters. The version to compare against.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

Parameters
nameAn 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.
See Also
WireTapServerHandle.getHostName.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
const char* WireTapServerHandle::getHostName ( ) const

Gets the name of the host machine on which the server is running.

Note
This method is preferred over WireTapServerInfo.getHostname.
Returns
A string containing the name of the host machine on which the server is running, or NULL on error. lastError() can be called to get the error string.
bool WireTapServerHandle::getHostTranslation ( int  index,
HostTranslation hostTranslation 
)
Parameters
[in]indexIndex of the host translation to fetch
[out]hostTranslationHostTranslation class describing the translation
const char* WireTapServerHandle::getHostUUID ( ) const

Gets the UUID of the host machine on which the server is running.

Returns
The UUID of the host machine on which the server is running, or NULL on error. lastError() can be called to get the error.
const WireTapServerId& WireTapServerHandle::getId ( ) const
Returns
The WireTapServerId object that was used to create this WireTapServerHandle. For complete server information, use getInfo().
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.

Returns
A string that is an identifier for the Wiretap server.
Note
As IP addresses can change for a given server (e.g. on a DHCP network), it can be preferable to use the persistent storage id (see WireTapServerHandle.getStorageId()).
bool WireTapServerHandle::getInfo ( WireTapServerInfo info) const

Gets an instance of WireTapServerInfo that contains the latest information about the Wiretap server.

Parameters
infoAn output parameter. The method fills this parameter with an instance of WireTapServerInfo that describes the Wiretap server.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
bool WireTapServerHandle::getNumHostTranslations ( int &  numHostTranslations)
Parameters
[out]numHostTranslationsthe number of host translations defined in the database.
bool WireTapServerHandle::getNumOsTypeTranslations ( int &  numOsTypeTranslations)
Parameters
[out]numOsTypeTranslationsthe number of type translations defined in the database.
bool WireTapServerHandle::getNumTranslationGroups ( int &  numGroups)
Parameters
[out]numGroupsThe number of groups defined in the database.
bool WireTapServerHandle::getOsTypeTranslation ( int  idx,
OsTypeTranslation osTypeTranslation 
)
Parameters
[in]idxIndex of the operating system translation to fetch
[out]osTypeTranslationOsTypeTranslation class describing the translation
bool WireTapServerHandle::getProduct ( WireTapStr product) const

Gets the name of the Wiretap server product.

Parameters
productAn output parameter. The method fills this parameter with a WireTapStr object that contains the name of the the Wiretap server product.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

Parameters
majorAn output parameter. The method sets this parameter to the major version number of the Wiretap protocol.
minorAn output parameter. The method sets this parameter to the minor version number of the Wiretap protocol.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
bool WireTapServerHandle::getRootNode ( WireTapNodeHandle root) const

Gets the root node of the Wiretap server.

Parameters
rootAn output parameter. The method fills this parameter with an instance of WiretapNodeHandle that gives access to the root node of the Wiretap server.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

Parameters
storageIdAn 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.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
bool WireTapServerHandle::getTranslationGroup ( int  index,
TranslationGroup group 
)
Parameters
[in]indexIndex of the translation group to fetch
[out]groupTranslationGroup class describing the translation group
bool WireTapServerHandle::getVendor ( WireTapStr vendor) const

Gets the vendor of the Wiretap server.

Parameters
vendorAn output parameter. The method fills this parameter with an instance of WireTapStr that contains the name of the company that sells the Wiretap server.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
bool WireTapServerHandle::getVersion ( int &  major,
int &  minor 
) const

Gets the version of the Wiretap server.

Parameters
majorAn output parameter. The method sets this parameter to the major version number of the Wiretap server.
minorAn output parameter. The method sets this parameter to the minor version number of the Wiretap server.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
bool WireTapServerHandle::invalidateCache ( )

Invalidate the server cache content.

Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

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.

Returns
The error string for the last operation (called on the current server handle) that failed.
bool WireTapServerHandle::ping ( unsigned  timeoutMS = 30000) const

Pings the Wiretap server.

Parameters
timeoutMSAn input parameter. Timeout in milliseconds.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

See Also
WireTapServerHandle.pushStream
Parameters
streamIdAn 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.
localFilePathAn input parameter. The path and name of the local file to be written.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

See Also
WireTapServerHandle.pullStream
Parameters
streamIdAn 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.
localFilePathAn input parameter. The path and name of the local file to be read and converted to a stream.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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).

Note
Use of this method can result in poor performance.
Parameters
frameIdAn 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.
bufferAn input parameter. The buffer to which the frame will be written. This value cannot be NULL.
bufferSizeAn input parameter. The number of bytes in the the buffer to be used for the frame.
nextFrameId1An 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
See Also
nextFrameId1

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:

Parameters
streamIdAn 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.
bufferAn input parameter. The buffer to be used for reading the stream. This value cannot be NULL.
bufferSizeAn 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.
itemOffsetAn input parameter. The number of the item at which to start reading the stream.
itemSizeInBytesAn input parameter. The number of bytes in each item in the stream. This information should be in the metadata for the stream.
numItemsAn input/output parameter. The number of items to be read from the stream / the number of items actually read.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

Parameters
[in]subjectSubject to monitor event on.
[in]handlerHandler object that will be called upon events reception.
[in]streamFormatAn input parameter describing the format of the metadata parameter
[in]metaDataAn optional parameter describing server- specific event parameters
Returns
true if registration worked.
Note
The same event handler can be used for multiple subjects
Servers older than 2013.3 do not support events.
Warning
This function should not be called more than once for a given subject.
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.

Parameters
reasonThis 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.

See Also
WireTapServerhandle.translatePaths()
Parameters
srcPathAn input parameter. A WireTapStr object containing the source path to be translated.
dstPathAn 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.
srcHostAn 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).
dstHostAn output parameter. The name or IP address of the host machine on which the destination paths are located.
srcOSAn input/output parameter. A constant that describes the operating system of the source machine. The constants are defined in WireTapOS::OsType.
dstOSAn input/output parameter. A constant that describes the operating system of the destination machine. The constants are defined in WireTapOS::OsType.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
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.

See Also
WireTapServerhandle.translatePath()
Note
The input parameters srcHost and dstHost can be set as follows:
Parameters
srcPathsAn input parameter. A WireTapStrList object.
dstPathsAn output parameter. A WireTapStrList object that points to an array of destination paths. The source and destination paths may be the same object.
srcHostAn 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).
dstHostAn 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.
srcOSAn 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.
dstOSAn 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.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.
bool WireTapServerHandle::unregisterEventHandler ( const WireTapNodeId subject,
WireTapNodeEvent::Handler handler 
)

Unregister an event handler registered on a given subject.

Parameters
[in]subjectSubject that was monitored.
[in]handlerHandler object associated to the subject.
Returns
true if unregistration worked.
Note
Servers older than 2013.3 do not support events.
Warning
This function should only be called for subjects that have been previously registered.
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).

Note
Use of this method can result in poor performance.
Parameters
frameIdAn input parameter. The ID of the frame to be written.
bufferAn input parameter. The buffer that contains the frame data. This value cannot be NULL.
bufferSizeAn input parameter. The number of bytes in the the buffer.
Note
The sample program createClip.cpp shows how to instantiate a WireTapClipFormat and obtain the buffer size from it.
Returns
true on success, false on failure. On failure, WireTapServerHandle::lastError() can be called to get the error string.

The documentation for this class was generated from the following file: