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

This class is a handle to a particular node on the Wiretap server to which the Wiretap client is currently connected. More...

Public Types

enum  ReadAheadHint { NO_READ_AHEAD = 0, READING_FORWARD = 1, READING_BACKWARD = -1 }
 

Public Member Functions

bool activateReadAhead ()
 
bool canCreateNode (const char *extendedType, bool &canCreate) const
 Gets if an ASCII metadata stream is associated with the current node. More...
 
bool createClipNode (const char *displayName, const WireTapClipFormat &clipFormat, const char *extendedType, WireTapNodeHandle &nodeHandle)
 Creates a clip node using an extended type defined by a Wiretap server. More...
 
WIRETAP_DEPRECATED bool createClipNode (const char *displayName, const WireTapClipFormat &clipFormat, int extendedType, WireTapNodeHandle &nodeHandle)
 Creates a clip node using an integer type defined by the IFFFS Wiretap server. More...
 
bool createNode (const char *displayName, const char *extendedType, WireTapNodeHandle &nodeHandle)
 Creates a node using an extended type defined by a Wiretap server. More...
 
bool createNode (const char *displayName, const char *extendedType, const char *streamFormat, const char *metaData, WireTapNodeHandle &nodeHandle)
 Creates a node using an extended type defined by a Wiretap server and initializes it with the supplied metadata. More...
 
WIRETAP_DEPRECATED bool createNode (const char *displayName, int extendedType, WireTapNodeHandle &nodeHandle)
 Creates a node using an integer type defined by the IFFFS Wiretap server. More...
 
bool destroyNode ()
 Destroys the node associated with the current node handle. More...
 
bool duplicateNode (const WireTapNodeHandle &dupeNode, const char *displayName, WireTapNodeHandle &newNode)
 Creates a duplicate of the supplied node and adds it to this node. More...
 
bool getAvailableMetaDataStream (int index, WireTapStr &format) const
 Gets the format of an ASCII metadata stream that is associated with the current node. More...
 
bool getChild (int index, WireTapNodeHandle &child) const
 Gets a child node of the current node by specifying the child's index. More...
 
bool getClipFormat (WireTapClipFormat &format) const
 Gets the clip format associated with the current clip node. More...
 
bool getDisplayName (WireTapStr &name) const
 Gets the display name of the current node. More...
 
bool getFrameId (int frameIndex, WireTapStr &frameId) const
 Gets the identifier of a frame associated with the current clip node. More...
 
bool getFrameIdPath (int frameIndex, WireTapStr &path) const
 Gets the file path of a frame in the current clip node. More...
 
bool getIsClipNode (bool &isClipNode) const
 Determines whether the current node is a clip node. More...
 
bool getIsMetaDataStreamAvailable (const char *streamFormat, bool &isAvailable) const
 Gets if an ASCII metadata stream is associated with the current node. More...
 
bool getMetaData (const char *streamFormat, const char *filter, const int depth, WireTapStr &metaData) const
 Gets ASCII metadata in a specified format for the current node. More...
 
bool getNbReadAheads (int &nbReadAheads) const
 
WireTapNodeIdgetNodeId () const
 Gets the persistent identifier of the current node. More...
 
WIRETAP_DEPRECATED bool getNodeType (int &type) const
 Gets the type of the current node expressed as an integer. More...
 
bool getNodeTypeStr (WireTapStr &type) const
 Gets a string that describes the type of the current node. More...
 
bool getNumAvailableMetaDataStreams (int &numStreams) const
 Gets the number of ASCII metadata streams that are associated with the current node. More...
 
bool getNumChildren (unsigned &numChildren) const
 Gets the number of child nodes found under the current node. More...
 
WIRETAP_DEPRECATED bool getNumChildren (int &numChildren) const
 
bool getNumFrames (unsigned &numberOfFrames) const
 Gets the number of frames of raw data associated with the current node, if it is a clip node. More...
 
WIRETAP_DEPRECATED bool getNumFrames (int &numberOfFrames) const
 
bool getParentNode (WireTapNodeHandle &parent) const
 Returns the parent node of the current node. More...
 
const WireTapServerHandlegetServer () const
 Gets a reference to the WireTapServerHandle for the current node. More...
 
bool getStreamId (WireTapStr &streamId) const
 Gets a string that is the identifier for a raw data stream associated with the node. More...
 
const char * lastError () const
 Gets the error string for the last operation that failed. More...
 
bool linkToFrames (const WireTapStr *paths, int numberOfPaths)
 Links to specified file paths in order to soft-import frames to the current clip node. More...
 
WireTapNodeHandleoperator= (const WireTapNodeHandle &nodeHandle)
 Assignment operator. More...
 
WireTapNodeHandleoperator= (WireTapNodeHandle &&nodeHandle) noexcept
 Move operator. More...
 
bool readFrame (int frameIndex, const void *params, size_t paramsSize, void *buffer, size_t bufferSize, ReadAheadHint readAheadHint=READING_FORWARD)
 Reads the contents of a frame at a specified index in the current clip node and writes it to a buffer. More...
 
WIRETAP_DEPRECATED bool readFrame (int frameIndex, void *buffer, size_t bufferSize, bool noReadAhead=false)
 
bool renameNode (const char *displayName)
 Renames the node associated with the current node handle. More...
 
bool setMetaData (const char *streamFormat, const char *metaData) const
 Sets ASCII metadata for the current node in a specified format. More...
 
void setNodeId (const WireTapNodeId &nodeId)
 Sets the persistent identifier of the current node. More...
 
bool setNumFrames (unsigned numberOfFrames)
 Preallocates the number of frames in the current clip node. More...
 
void setServer (const WireTapServerHandle &server)
 Sets the WireTapServerHandle for the current node. More...
 
 WireTapNodeHandle ()
 Constructs a new WireTapNodeHandle object with no member variables set. More...
 
 WireTapNodeHandle (const WireTapNodeHandle &nodeHandle)
 Copy constructor. More...
 
 WireTapNodeHandle (WireTapNodeHandle &&nodeHandle) noexcept
 Move constructor. More...
 
 WireTapNodeHandle (const WireTapServerHandle &server, const WireTapNodeId &nodeId)
 Constructs a new WireTapNodeHandle object using references to instances of WireTapServerHandle and WireTapNodeId. More...
 
 WireTapNodeHandle (const WireTapServerHandle &server, const char *nodeIdStr)
 Constructs a new WireTapNodeHandle object using a reference to a WireTapServerHandle object and a string that contains a node ID. More...
 
bool writeFrame (int frameIndex, const void *buffer, size_t bufferSize)
 Reads the contents of a buffer and writes it to a frame at a specified index in the current clip node. More...
 
virtual ~WireTapNodeHandle ()
 Destructor. More...
 

Detailed Description

This class is a handle to a particular node on the Wiretap server to which the Wiretap client is currently connected.

A node represents a directory or file in the file system that is exposed by the Wiretap server.

WireTapNodeHandle uses a node ID and a server handle to uniquely refer to the node. It provides a set of functions to interface with the node via the Wiretap protocol. Node information is read and cached within the node object. The Wiretap Client API is not a distributed object model. The information obtained using a node handles is not updated dynamically. To update the information, the relevant get method(s) must be called.

Nodes come in two flavors: nodes and clip nodes. A clip node is simply a specialization of node.

The Wiretap Client API deliberately dissociates itself from the extensive and dynamic list of node types provided by most proprietary database implementations (for example, project, library, reel, and so on). Wiretap base functionality is confined to generic node manipulation, and to basic clip and frame I/O services.

The interpretation of extended types as well as metadata is the responsibility of the Wiretap client. For example, all nodes have an extended type defined by the implementation of the underlying database on the Wiretap server. A Wiretap client that is aware of the proprietary implementation of the Wiretap server(s) with which it will communicate, can interpret these extended types to provide specific functionality. The vendor, product name, and version of a Wiretap server's database implementation can be obtained from the instance of WireTapServerHandle that represents the connection to the server. In this way, specific products can coordinate private interoperability efforts among themselves, or define public interoperability standards.

Member Enumeration Documentation

Enumerator
NO_READ_AHEAD 
READING_FORWARD 
READING_BACKWARD 

Constructor & Destructor Documentation

WireTapNodeHandle::WireTapNodeHandle ( )

Constructs a new WireTapNodeHandle object with no member variables set.

WireTapNodeHandle::WireTapNodeHandle ( const WireTapNodeHandle nodeHandle)

Copy constructor.

Constructs a new WireTapNodeHandle object that duplicates the content of the original.

Parameters
nodeHandleAn input parameter. The WiretapNodeHandle object that is to be copied.
WireTapNodeHandle::WireTapNodeHandle ( WireTapNodeHandle &&  nodeHandle)
noexcept

Move constructor.

Constructs a new WireTapNodeHandle object by moving the content of the original.

Parameters
nodeHandleAn input parameter. The WiretapNodeHandle object that is to be moved.
WireTapNodeHandle::WireTapNodeHandle ( const WireTapServerHandle server,
const WireTapNodeId nodeId 
)

Constructs a new WireTapNodeHandle object using references to instances of WireTapServerHandle and WireTapNodeId.

Wiretap clients may need to use this constructor if the storage device on which the node is located has been switched from one Wiretap server to another. In this situation, a Wiretap client that has retained the storage ID along with the node ID, can do the following:

  1. Call WireTapServerList.resolveNodeId to obtain the server ID for the new server
  2. Construct a new WireTapServerHandle from the server ID.
  3. Construct a new WireTapNodeHandle using this constructor.
Parameters
serverAn input parameter. A handle to the server on which the node is located.
nodeIdAn input parameter. A WireTapNodeId object that contains the ID of the node for which a handle is to be constructed.
WireTapNodeHandle::WireTapNodeHandle ( const WireTapServerHandle server,
const char *  nodeIdStr 
)

Constructs a new WireTapNodeHandle object using a reference to a WireTapServerHandle object and a string that contains a node ID.

Wiretap clients may need to use this constructor if the storage device on which the node is located has been switched from one Wiretap server to another. In this situation, a Wiretap client that has retained the storage ID and has a string containing a node ID, can do the following:

  1. Call WireTapServerList.resolveNodeId to obtain the server ID for the new server
  2. Construct a new WireTapNodeHandle using this constructor.
Parameters
serverAn input parameter. A handle to the server on which the node is located.
nodeIdStrAn input parameter. A string that contains the ID of the node for which a handle is to be constructed.
virtual WireTapNodeHandle::~WireTapNodeHandle ( )
virtual

Destructor.

Member Function Documentation

bool WireTapNodeHandle::activateReadAhead ( )
Note
activateReadAhead is not required under normal circumstances. It should not be used in general purpose code.
bool WireTapNodeHandle::canCreateNode ( const char *  extendedType,
bool &  canCreate 
) const

Gets if an ASCII metadata stream is associated with the current node.

A Wiretap client can determine if a given metadata stream is available with this method.

Parameters
extendedTypeAn input parameter. A string that is one of the extended types defined by the Wiretap server on which the node is to be created.
canCreateAn output parameter. The method fills this parameter to true if the extended type is a valid type of child for the current node.
Returns
true if it was possible to get validity of the extended type for the current node, false if it was not possible to get the validity of the extended type for the current node. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::createClipNode ( const char *  displayName,
const WireTapClipFormat clipFormat,
const char *  extendedType,
WireTapNodeHandle nodeHandle 
)

Creates a clip node using an extended type defined by a Wiretap server.

This is the preferred method for instanting a clip node. The other method for creating clip nodes (using an integer for the extended type) is deprecated.

Note
The sample program createClip.cpp supplied with the SDK shows how to use this method to create a clip node.

To create a node that is not a clip node, see WireTapNodeHandle.createNode

Parameters
displayNameAn input parameter. The name to use as a label on the node in a user interface. Display names do not have to be unique.
clipFormatAn input/output parameter. On input, a Wiretap client should supply an instance of WireTapClipFormat whose properties are set to appropriate values. On output, the Wiretap server will have set certain properties such as buffer size.
extendedTypeAn input parameter. A string that is one of the extended types defined by the Wiretap server on which the node is to be created.
nodeHandleAn output parameter. The method fills this parameter with an instance of WireTapNodeHandle with the specified display name, clip format, and extended type.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
WIRETAP_DEPRECATED bool WireTapNodeHandle::createClipNode ( const char *  displayName,
const WireTapClipFormat clipFormat,
int  extendedType,
WireTapNodeHandle nodeHandle 
)

Creates a clip node using an integer type defined by the IFFFS Wiretap server.

Deprecated:
Since Wiretap 2007.1. The preferred method is WireTapNodeHandle.createClipNode( const char *displayName, const WireTapClipFormat &format, const char *extendedType, WireTapNodeHandle &nodeHandle )
bool WireTapNodeHandle::createNode ( const char *  displayName,
const char *  extendedType,
WireTapNodeHandle nodeHandle 
)

Creates a node using an extended type defined by a Wiretap server.

This is the preferred method for instantiating any node that is not a clip. The other method for creating non-clip nodes (using an integer for the extended type) is deprecated.

To create a clip node, use WireTapNodeHandle.createClipNode( const char *displayName, const &WireTapClipFormat &f, const char *extendedType, &WireTapNodeHandle &node_return ).

Parameters
displayNameAn input parameter. The name to use as a label on the node in a user interface. Display names do not have to be unique.
extendedTypeAn input parameter. A string that is one of the extended types defined by the Wiretap server on which the node is to be created.
nodeHandleAn output parameter. The method fills this parameter with an instance of WireTapNodeHandle with the specified display name and extended type.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::createNode ( const char *  displayName,
const char *  extendedType,
const char *  streamFormat,
const char *  metaData,
WireTapNodeHandle nodeHandle 
)

Creates a node using an extended type defined by a Wiretap server and initializes it with the supplied metadata.

This is the preferred method for instantiating any node that is not a clip. The other method for creating non-clip nodes (using an integer for the extended type) is deprecated.

Parameters
displayNameAn input parameter. The name to use as a label on the node in a user interface. Display names do not have to be unique.
extendedTypeAn input parameter. A string that is one of the extended types defined by the Wiretap server on which the node is to be created.
streamFormatAn input parameter. A string that describes the the format of the stream. For example, to set XML format metadata for a project or user node on an IFFFS Wiretap server, this parameter should be set to "XML".
See Also
setMetaData
Parameters
metaDataAn input parameter. An ASCII string that defines the metadata to associate with the node.
See Also
setMetadata
Parameters
nodeHandleAn output parameter. The method fills this parameter with an instance of WireTapNodeHandle with the specified display name and extended type.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
WIRETAP_DEPRECATED bool WireTapNodeHandle::createNode ( const char *  displayName,
int  extendedType,
WireTapNodeHandle nodeHandle 
)

Creates a node using an integer type defined by the IFFFS Wiretap server.

Deprecated:
Since Wiretap 2007.1. The preferred method is WireTapNodeHandle.createNode( const char *displayName, const char *extendedType, WireTapNodeHandle &nodeHandle )
bool WireTapNodeHandle::destroyNode ( )

Destroys the node associated with the current node handle.

Returns
true on success, false on failure. On success, the node is no longer in the file system of the Wiretap server, the current node handle is no longer valid, and function calls on the node handle generate errors. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::duplicateNode ( const WireTapNodeHandle dupeNode,
const char *  displayName,
WireTapNodeHandle newNode 
)

Creates a duplicate of the supplied node and adds it to this node.

Parameters
dupeNodeThe node to be duplicated
displayNameThe display name to apply to the duplicated node
newNodeA reference to the new, duplicated node
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getAvailableMetaDataStream ( int  index,
WireTapStr format 
) const

Gets the format of an ASCII metadata stream that is associated with the current node.

After determining how many metadata streams are available using the WireTapNodeHandle.getNumAvailableMetaDataStreams method, a Wiretap client can iterate on the stream indexes to get the formats of the metadata streams (using this method) or to get the actual metadata (using WireTapNodeHandle.getMetaData).

If the format of the metadata stream is already known, the actual stream can be obtained directly with the WireTapNodeHandle.getMetaData method.

Parameters
indexAn input parameter. The index of the metadata stream to be queried.
formatAn output parameter. The method fills this parameter with a WireTapStr object that is the format of the metadata (for example, XML).
Returns
true if it was possible to get the metadata format, false if it was not possible to get the format. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getChild ( int  index,
WireTapNodeHandle child 
) const

Gets a child node of the current node by specifying the child's index.

The total number of child nodes for the current node is obtained by calling WireTapNodeHandle.getNumChildren.

Parameters
indexAn input parameter. Node indexes start at 0. An index less than zero or equal to the total number of children (obtained by calling WireTapNodeHandle.getNumChildren) will cause an error.
childAn output parameter. The method fills this parameter with an instance of WireTapNodeHandle for the node at the specified index.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getClipFormat ( WireTapClipFormat format) const

Gets the clip format associated with the current clip node.

This method fails if the current node is not a clip node.

Parameters
formatAn output parameter. The method fills this parameter with a WireTapClipFormat object of the type set when the node was created.
Returns
true if the node is a clip node and the format was found, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getDisplayName ( WireTapStr name) const

Gets the display name of the current node.

Parameters
nameAn output parameter. The method fills this parameter with a WireTapStr object containing the display name for the node. Display names need not be unique.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getFrameId ( int  frameIndex,
WireTapStr frameId 
) const

Gets the identifier of a frame associated with the current clip node.

This method fails if the current node is not a clip node.

The total number of frames in the clip can be obtained with the method WireTapNodeHandle.getNumFrames.

The frame ID (obtained with this method) and the frame file path (obtained with WireTapNodeHandle.getFrameIdPath) allow Wiretap clients to access the raw frame directly rather than through the Wiretap server TCP connection. Depending on the bandwidth of the direct connection to the storage device, a significant gain in performance can be achieved.

Parameters
frameIndexAn input parameter. The index of the frame whose ID is being sought. The total number of frames in the clip is obtained with the method WireTapNodeHandle.getNumFrames.
frameIdAn output parameter. The method fills this method with a WireTapStr object that contains the frame identifier.
Returns
true if the node is a clip node, and it was possible to get the frame ID; false if the node is not a clip node, or it was not possible to get the frame ID. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getFrameIdPath ( int  frameIndex,
WireTapStr path 
) const

Gets the file path of a frame in the current clip node.

This method fails if the current node is not a clip node.

The total number of frames in the clip can be obtained with the method WireTapNodeHandle.getNumFrames.

The frame ID (obtained with WireTapNodeHandle.getFrameId) and the file path (obtained with this method) allow clients to access the raw frame directly rather than through the Wiretap server TCP connection. Depending on the bandwidth of the direct connection to the storage device, a significant gain in performance can be achieved.

Parameters
frameIndexAn input parameter. The index of the frame whose frame path is sought.
pathAn output parameter. The method fills this method with a WireTapStr object that contains the file path of the frame. If the file path is not available, the path will be set to the empty string.
Returns
true if the path variable was set to set to a valid path or to an empty string; false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getIsClipNode ( bool &  isClipNode) const

Determines whether the current node is a clip node.

Parameters
isClipNodeAn output parameter. The method sets this parameter to true if the node is a clip node, or sets it to false if the node is not a clip node.
Returns
true if the method is able to determine whether the node is a clip node, false if the method cannot determine whether the node is a clip node. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getIsMetaDataStreamAvailable ( const char *  streamFormat,
bool &  isAvailable 
) const

Gets if an ASCII metadata stream is associated with the current node.

A Wiretap client can determine if a given metadata stream is available with this method.

Parameters
streamFormatAn input parameter. A string that describes the the format of the stream. For example, to set XML format metadata for a project or user node on an IFFFS Wiretap server, this parameter should be set to "XML".
isAvailableAn output parameter. The method fills this parameter to true if the stream is available for the current node.
Returns
true if it was possible to get availability of the metadata stream, false if it was not possible to get the availability of the stream. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getMetaData ( const char *  streamFormat,
const char *  filter,
const int  depth,
WireTapStr metaData 
) const

Gets ASCII metadata in a specified format for the current node.

Wiretap clients can use this method directly if the desired type of metadata is known (for example, "XML"). If the desired type of metadata stream is not known or if there are multiple metadata streams, the available metadata stream(s) for the current node can be iterated through and obtained with a combination of methods:

Not all nodes have ASCII metadata associated with them. See the Wiretap Developer's Guide for more information about the types of nodes that support metadata and which metadata formats they support.

Parameters
streamFormatAn input parameter. A string that describes the format of the stream. For example, to get XML format metadata for a project or user node on an IFFFS Wiretap server, this parameter should be set to "XML".
filterAn input parameter. A string that is the name of an element in the metadata stream. For some node types, it is possible to select individual elements in the metadata stream. See the Wiretap Developer's Guide for more information. To get the entire metadata stream, set this parameter to an empty string ("").
depthAn input parameter. An integer that specifies how many levels to recurse within the metadata structure. Not all nodes or metadata streams support this parameter. See the Wiretap Developer's Guide for more information.
metaDataAn output parameter. The method fills this parameter with a WireTapStr object that contains the metadata for the node as an ASCII string.
Returns
true if it was possible to get the metadata specified, false if it was not possible to get the metadata. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getNbReadAheads ( int &  nbReadAheads) const
WireTapNodeId& WireTapNodeHandle::getNodeId ( ) const

Gets the persistent identifier of the current node.

Note
Normally, a node ID is only valid in the context of the WireTapServerHandle that was connected to the Wiretap server when the node was created. After a Wiretap clients gets the node ID, the storage device (on which the node is actually stored) could be switched to a different Wiretap server host. To be able to use node IDs at any time (even if a storage device on which the node resides is switched to a different host), Wiretap clients should retain the storage ID for all nodes when the nodes are created. The storage ID can be obtained by calling WireTapServerHandle.getStorageId. In case of difficulty accessing a node using its node ID, Wiretap clients can call WireTapServerList.resolve to obtain the coordinates of the Wiretap server host that corresponds to the retained storage ID, and then create a new server handle for the new Wiretap server host.
Returns
A WireTapNodeId object that contains the persistent identifier of the node.
WIRETAP_DEPRECATED bool WireTapNodeHandle::getNodeType ( int &  type) const

Gets the type of the current node expressed as an integer.

Parameters
typeAn output parameter. The method sets this parameter to the integer value for the extended node type. Each Wiretap server defines its own extended node types. The default value (for a node with no extended type) is 0.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
Deprecated:
Since Wiretap 2007.1. The preferred method is WireTapNodeHandle.getNodeTypeStr.
bool WireTapNodeHandle::getNodeTypeStr ( WireTapStr type) const

Gets a string that describes the type of the current node.

Parameters
typeAn output parameter. The method fills this parameter with a WireTapStr object that gives access to the node type as a string. This could be the value entered when the node was created or on of the extended node types defined by the Wiretap server. Each Wiretap server defines its own extended node types.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getNumAvailableMetaDataStreams ( int &  numStreams) const

Gets the number of ASCII metadata streams that are associated with the current node.

A Wiretap client can determine the number of metadata streams that are available with this method, and then it can iterate and obtain the stream types (using the WireTapNodeHandle.getAvailableMetaDataStream method) and the actual metadata (using the WireTapNodeHandle.getMetaData method).

Parameters
numStreamsAn output parameter. The method fills this parameter with the number of metadata streams that are available for the current node.
Returns
true if it was possible to get the number of metadata streams, false if it was not possible to get the number of streams. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::getNumChildren ( unsigned &  numChildren) const

Gets the number of child nodes found under the current node.

Parameters
numChildrenAn output parameter. The method fills this parameter with the number of child nodes of the current node.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
WIRETAP_DEPRECATED bool WireTapNodeHandle::getNumChildren ( int &  numChildren) const
bool WireTapNodeHandle::getNumFrames ( unsigned &  numberOfFrames) const

Gets the number of frames of raw data associated with the current node, if it is a clip node.

Parameters
numberOfFramesAn output parameter. The number of frames that are in the clip.
Returns
true if the node is a clip node, and it was possible to get the number of frames; false if the node is not a clip node, or it was not possible to get the number of frames. On failure, WireTapNodeHandle::lastError() can be called to get the actual error string.
WIRETAP_DEPRECATED bool WireTapNodeHandle::getNumFrames ( int &  numberOfFrames) const
bool WireTapNodeHandle::getParentNode ( WireTapNodeHandle parent) const

Returns the parent node of the current node.

Parameters
parentAn output parameter. The method fills this parameter with an instance of WireTapNodeHandle for the parent node.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
const WireTapServerHandle& WireTapNodeHandle::getServer ( ) const

Gets a reference to the WireTapServerHandle for the current node.

A node handle and a node ID are only valid in the context of the server under which they were created. A node's server is normally set when the node handle is created (by methods such as WireTapNodeHandle.createNode, WireTapNodeHandle.createClipNode, WireTapServerHandle.getRootNode).

Returns
A reference to the WireTapServerHandle for the current node.
bool WireTapNodeHandle::getStreamId ( WireTapStr streamId) const

Gets a string that is the identifier for a raw data stream associated with the node.

Note
Wiretap clients would typically call this method to obtain a stream ID for the node before calling WireTapServerHandle.readStream.
Parameters
streamIdAn output parameter. A string that is the identifier for the raw data stream associated with the node. If the node does not have a raw data stream associated with it, or if the Wiretap server does not support raw data streams, an empty string ("") is returned.
Returns
true if a WireTapStr object was updated with a valid value (empty or not empty, see the streamId parameter above) is returned; false if it was not possible to update streamId. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
const char* WireTapNodeHandle::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 node handle) that failed.
bool WireTapNodeHandle::linkToFrames ( const WireTapStr paths,
int  numberOfPaths 
)

Links to specified file paths in order to soft-import frames to the current clip node.

This method fails if the current node is not a clip node.

Note
The sample program createSoftClip.cpp shows how to use this method.

The clip node must be empty when this method is called. The frame formats of the individual frame files must match the clip format of the clip node or an error will be generated. The frame paths are automatically translated to use the native mount point of the server, using the Wiretap path translation services.

Parameters
pathsAn input parameter. A WireTapStr object that points to an array of paths for the frame files to be linked to.
numberOfPathsAn input parameter. The number of frame paths that are in the paths parameter.
Returns
true if the node is a clip node, and it was possible to link to frames; false if the node is not a clip node, or it was not possible to link to the frames. On failure, WireTapNodeHandle::lastError() can be called to get the actual error string.
WireTapNodeHandle& WireTapNodeHandle::operator= ( const WireTapNodeHandle nodeHandle)

Assignment operator.

Initializes a WireTapNodeHandle object that duplicates the content of the original.

Parameters
nodeHandleAn input parameter. The WiretapNodeHandle object that is to be copied.
WireTapNodeHandle& WireTapNodeHandle::operator= ( WireTapNodeHandle &&  nodeHandle)
noexcept

Move operator.

Initializes a WireTapNodeHandle object by moving the content of the original.

Parameters
nodeHandleAn input parameter. The WiretapNodeHandle object that is to be moved.
bool WireTapNodeHandle::readFrame ( int  frameIndex,
const void *  params,
size_t  paramsSize,
void *  buffer,
size_t  bufferSize,
ReadAheadHint  readAheadHint = READING_FORWARD 
)

Reads the contents of a frame at a specified index in the current clip node and writes it to a buffer.

This method fails if the current node is not a clip node.

Wiretap clients can call WireTapNodeHandle.getNumFrames to determine the number of frames to be read from the node. Then they would iterate through the frames and call this method to read the frames from the buffer. The sample program readFrames.cpp (which is included in the SDK) shows how to use this method.

Note
Use WireTapServerHandle.readFrame if only the frame ID is known but it is not associated with a clip node.
Parameters
frameIndexAn input parameter. The index of the frame to be read. Frame indexes start at 0. An index less than zero or equal to the number of available frames (obtained by calling WireTapNodeHandle.getNumFrames) will generate an error.
paramsAn input parameter. Contains black data on the parameter to use to decode and read the frame. Might be 0 if none needed.
paramsSizeAn input parameter. The number of bytes in the the buffer to be used as the read parameters.
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. The buffer size must be equal to or greater than the value obtained from the WireTapClipFormat object for the node. The sample program readFrames.cpp (included in the SDK) shows how to find the minimum buffer size.
readAheadHintBy default, the next frames in the clip sequence will be sent to the server as a hint to prepare (i.e. read ahead) and decode the next frame. Setting this parameter to NO_READ_AHEAD will disable this functionality. This option would normally be used when generating a thumbnail. Setting this parameter to READING_BACKWARD will resverse the direction of the 'next frame'.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
WIRETAP_DEPRECATED bool WireTapNodeHandle::readFrame ( int  frameIndex,
void *  buffer,
size_t  bufferSize,
bool  noReadAhead = false 
)
Deprecated:
Since Wiretap 2010.1.1. The preferred method is WireTapNodeHandle.readFrame() with params and readAheadHint.
bool WireTapNodeHandle::renameNode ( const char *  displayName)

Renames the node associated with the current node handle.

This method can be used to change the display name of a node.

Note
This may have the effect of changing the node's id.
Parameters
displayNameAn input parameter. The name to use as a label on the node in a user interface.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
bool WireTapNodeHandle::setMetaData ( const char *  streamFormat,
const char *  metaData 
) const

Sets ASCII metadata for the current node in a specified format.

Not all nodes can have ASCII metadata associated with them. See the Wiretap Developer's Guide for more information about the types of nodes that support metadata and which metadata formats they support.

Parameters
streamFormatAn input parameter. A string that describes the the format of the stream. For example, to set XML format metadata for a project or user node on an IFFFS Wiretap server, this parameter should be set to "XML".
metaDataAn input parameter. A WireTapStr object containing an ASCII string that defines the metadata to associate with the node.
Returns
true if it was possible to set the metadata as specified, false if it was not possible to set the metadata. On failure, WireTapNodeHandle::lastError() can be called to get the error string.
void WireTapNodeHandle::setNodeId ( const WireTapNodeId nodeId)

Sets the persistent identifier of the current node.

See Also
WireTapNodeHandle.getNodeId.
Parameters
nodeIdA WireTapNodeId object that contains the persistent identifier of the node.
bool WireTapNodeHandle::setNumFrames ( unsigned  numberOfFrames)

Preallocates the number of frames in the current clip node.

This method fails if the current node is not a clip node.

Note
The sample program createClip.cpp shows how to use this method.
Parameters
numberOfFramesAn input parameter. The number of frames to allocate for the clip.
Returns
true if the node is a clip node, and it was possible to set the number of frames; false if the node is not a clip node, or it was not possible to set the number of frames. On failure, WireTapNodeHandle::lastError() can be called to get the actual error string.
void WireTapNodeHandle::setServer ( const WireTapServerHandle server)

Sets the WireTapServerHandle for the current node.

A node handle and a node ID are only valid in the context of the server under which they were created. A node's server is normally set when the node handle is created (by any number of methods such as WireTapNodeHandle.createNode, WireTapNodeHandle.createClipNode, WireTapServerHandle.getRootNode, WireTapServerList.getNode). Wiretap clients should not need to call this method in normal circumstances.

Parameters
serverAn input parameter. A reference to the WireTapServerHandle for the current node.
bool WireTapNodeHandle::writeFrame ( int  frameIndex,
const void *  buffer,
size_t  bufferSize 
)

Reads the contents of a buffer and writes it to a frame at a specified index in the current clip node.

This method fails if the current node is not a clip node.

Wiretap clients can call WireTapNodeHandle.getNumFrames to obtain the number of frames in the clip node. Then they would this method to write the frames to the buffer. The sample program createClip.cpp (which is included in the SDK) shows how to use this method.

Note
Use WireTapServerHandle.writeFrame can be used if only the frame ID is known but it is not associated with a node.
Parameters
frameIndexAn input parameter. The index of the frame to be written.
bufferAn output parameter. The buffer from which the frame will be read. This value cannot be NULL.
bufferSizeAn input parameter. The number of bytes in the the buffer to be used for the frame. The buffer size must be equal to or greater than the value obtained from the WireTapClipFormat object for the node. The sample program createClip.cpp (included in the SDK) shows how to find the minimum buffer size.
Returns
true on success, false on failure. On failure, WireTapNodeHandle::lastError() can be called to get the error string.

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