This section explains how Wiretap handles some basic programming issues. You may also want to look at the FAQs in General API Issues.
All internal symbols of the Wiretap Client and Server APIs are protected by the WireTap prefix. Both the C++ and Python versions of the API use the prefix WireTap in the names of all classes and global functions.
Error messages generated by Wiretap are intended to be viewed by end users. Each Wiretap server implementation generates its own errors. Often, the error strings are generated dynamically and include contextual information.
Three classes fetch and manipulate data on a Wiretap server:
An error message is issued if a failure occurs during calls to any of their member functions that interact with a Wiretap server. Each of the above-mentioned classes has a member function called lastError() that looks for the error message. The error string must be used or stored immediately, since it will be overwritten the next time a member function is called.
All member functions that communicate with a Wiretap server, return a boolean value: true on success, false on failure. As shown in the sample programs (for example, listChildren.C and wiretap_get_children.py), this return value should be checked and, if it is false, lastError() must be called.
String Return Values – Wiretap guarantees that all methods that return string pointers will return a valid string (never a null pointer).
Custom String Class – API libraries often redefine standard library data types (like std::string) to avoid problems when a host application chooses a different standard C library from the one used by the API library. The Wiretap API includes the WireTapStr class for this reason. This means that Wiretap clients must duplicate strings when converting from WireTapStr to their own string class for internal use. WireTapStr is also needed for the Python version of the Wiretap API. Python does not allow basic types like string to be passed by reference. A WireTapStr object can be passed to methods that need to return strings in an output parameter.
Wiretap node handles and server handles can exist in different threads, but a single handle object cannot be used simultaneously in several threads. For example, multiple threads can be used to traverse a node hierarchy, but they cannot share the same node or server handles.
The one exception to this rule is the WireTapNodeHandle.stop function, which is intended to be used in an asynchronous thread to halt a pending request on a handle.
The Wiretap server API is internationalized so that your Wiretap client can be compiled for any language or locale. Error messages received from the operating system will be localized. Only the English version of the IFFFS Wiretap server is installed with Visual Effects and Finishing applications so its errors are in English.