Wiretap API  <small>Wiretap 2021</small>
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
WireTapClientAPI.h File Reference

Classes

class  WireTapServerHandle::HostTranslation
 This class is used to retrieve information of a host translation defined in the path translation database. More...
 
class  WireTapServerHandle::OsTypeTranslation
 This class is used to retrieve information of a operating system type translation defined in the path translation database. More...
 
class  WireTapServerHandle::TranslationGroup
 
class  WireTapClient
 Scope base Wiretap client. More...
 
class  WireTapNodeHandle
 This class is a handle to a particular node on the Wiretap server to which the Wiretap client is currently connected. More...
 
class  WireTapServerHandle
 This class represents a connection to a Wiretap server on the Wiretap network. More...
 
class  WireTapServerList
 This class prepares a list of the Wiretap servers that can be accessed by the Wiretap client. More...
 

Functions

void WireTapClientGetVersion (int &majorVersion, int &minorVersion, int &maintVersion)
 Gets the version of the Wiretap Client API. More...
 
bool WireTapClientInit ()
 Initializes the Wiretap Client API. More...
 
void WireTapClientReleaseUnusedConnections (bool force)
 Release unused shared server connections. More...
 
void WireTapClientUninit ()
 Uninitializes the Wiretap Client API. More...
 
bool WireTapFindChild (const WireTapNodeHandle &parentNode, const char *displayName, WireTapNodeHandle &child)
 Gets a handle for the node with a specified display name that is the child of a specified parent node. More...
 
void WireTapRegisterDisconnectCallBack (void cb(const WireTapServerId &))
 Register a callback function for server disconnections. More...
 
bool WireTapResolveDisplayPath (const WireTapServerHandle &server, const char *displayPath, WireTapNodeHandle &child)
 Gets a node handle that corresponds to the specified display name on the specified Wiretap server. More...
 

Function Documentation

void WireTapClientGetVersion ( int &  majorVersion,
int &  minorVersion,
int &  maintVersion 
)

Gets the version of the Wiretap Client API.

Gets the full version of the current instance of the Wiretap Client API. Useful if it is necessary to display or verify the version of the API at runtime. The version is obtained in three parts: major.minor.maintenance (for example: 2008.1.0).

Parameters
majorVersionAn output parameter. The function sets this parameter to the major version of the API.
minorVersionAn output parameter. The function sets this parameter to the minor version of the API.
maintVersionAn output parameter. The function sets this parameter to a maintenance suffix. If the version is not a maintenance release, this is is set to 0.
bool WireTapClientInit ( )

Initializes the Wiretap Client API.

This function must be called once at startup, before any other calls to the Wiretap Client API are made.

Returns
true if the Client API was initialized successfully; false if the API was not initialized. On success, the rest of the Wiretap Client API can be used.
See Also
WireTapClientUninit
void WireTapClientReleaseUnusedConnections ( bool  force)

Release unused shared server connections.

It will release shared connections that have been unused for more than 10 seconds, that is, that are no longer tied to any WireTapServerHandle.

Parameters
forceAn input parameter. If true, it will release all unused connections independently from how long they have been unused.
See Also
WireTapClientInit
void WireTapClientUninit ( )

Uninitializes the Wiretap Client API.

This function must be called at shutdown.

Warning
No further Wiretap Client SDK function calls should be done after calling this function, including calls done by static objects if this is called from main().
See Also
WireTapClientInit
bool WireTapFindChild ( const WireTapNodeHandle parentNode,
const char *  displayName,
WireTapNodeHandle child 
)

Gets a handle for the node with a specified display name that is the child of a specified parent node.

This function gets a node whose display name matches the name specified as an input parameter. The node is the first child node with that display name that is found under the parent node (also specified as an input parameter). Since Wiretap does not prevent several nodes from having the same display name, this method does not necessarily always find the same node.

Note
The uniqueness of a node on a given server is determined by its node ID not its display name. The node ID should be used as the persistent reference to a node (rather than a display name).
Parameters
parentNodeAn input parameter. The node whose child is being sought.
displayNameAn input parameter. The displayName of the node sought. This parameter is case-sensitive. This method verifies the display name of each child node until it finds one that matches.
childAn output parameter. The method places an instance of WireTapNodeHandle representing the child node in this parameter.
Returns
true if a child node with the specified name was found for the parentNode; false if the parent node does not have any children with the specified display name.
void WireTapRegisterDisconnectCallBack ( void   cbconst WireTapServerId &)

Register a callback function for server disconnections.

This function asks that the provided callback function be called when a server forced our disconnection (due to a crash or an externally requested shutdown). It will not be called following a client-initiated disconnection.

Note
The callback function will be called only from within a Wiretap API call.

This callback replaces the need for calling isConnected() after every reported error. It can then be used to flag the need for server reinitialization. (Remember that once the server is restarted, following Wiretap API calls will automatically reconnect to the server.)

Note
Do not make Wiretap API calls in the callback function as this may cause a dead-lock. The typical procedure is to set a flag which will be checked before calling the Wiretap API again.
Callback is registered until replaced by another function or NULL. Only one callback can be registered.
Parameters
cbA callback function which takes as argument the serverId initially passed to the WireTapServerHandle constructor.
bool WireTapResolveDisplayPath ( const WireTapServerHandle server,
const char *  displayPath,
WireTapNodeHandle child 
)

Gets a node handle that corresponds to the specified display name on the specified Wiretap server.

Gets a node handle object that represents the node at the specified path on the specified Wiretap server. The specified path terminates with the display name of the node. The search is case-sensitive and does not handle wildcards.

Parameters
serverAn input parameter. A Wiretap server. The method will attempt to resolve the path (specified in the displayPath parameter) on this server.
displayPathAn input parameter. A fully or partially qualified path to a node on the server. The method will attempt to resolve this path. displayPath must be formed as follows:
  • displayPath must end with the node display name.
  • Valid display names for nodes do not contain forward or backward slash characters.
  • The path separator can be either a forward or a backward slash.
  • P ath separators can be doubled. For example: "//"
  • The path can have leading and trailing slashes.
  • Mixing of forward and backward slashes is legal.
  • For relative paths:
    • "/./" is supported.
    • "/../" not supported.
childAn output parameter. After a successful search, this parameter contains an instance of WireTapNodeHandle that points to the child node.
Returns
true if a node with the specified path was found on the specified server; false if the server does not have a node with the specified path or if the specified path is not well-formed.