Summary
The XStream® HDVR® SDK includes built-in protocols for high speed communication between client and server applications. Separate mechanisms are provided for thin client applications (where the client and server applications run on different computers) and thick client applications (where the client and server applications are run on the same computer). The thick client mechanism makes use of a shared memory space to exchange client and server data, whereas the thin client makes use of network socket based communication. These communication mechanisms are implemented in the hdrclocalstr.dll (thick client) and hdrcsockstr.dll (thin client) DLL files, and are loaded at runtime by the client and server applications. Although the client-server communication protocols provided are suitable for most applications, the XStream HDVR SDK also includes a mechanism that allows developers to implement their own thin and thick client communication plugins. For instance, a developer may want to implement Transport Layer Security (TLS), Secure Sockets Layer (SSL) or other encrypted protocol.
The XStream HDVR SDK distribution contains example applications that demonstrate and provide source code for the implementation of a custom network protocol.
The SSL Network Streaming example describes how to create a network plugin that supports SSL streaming.
XStream HDVR client and server applications communicate with each other through class methods implemented by the ISimpleStream class interface. The ISimpleStream interface is defined in the simplestream.h file that is included with the XStream HDVR distribution. A class that inherits from and implements the ISimpleStream interface supports XStream HDVR custom network protocols. This class is then compiled to a .DLL (Microsoft Windows), .SO (Linux), or .DYLIB (OSX) file and loaded at runtime by the client or server application. ISimpleStream based classes must be implemented in C++.
RRESULT ISimpleStream::ReadWrite(bool bReadWrite, void* pBuffer, h_uint32 bufferSize, h_uint32* pReadWriteSize)
The ISimpleStream::ReadWrite() method is responsible for reading data from and writing data to the network (or other) communication mechanism. This method takes four parameters. The first parameter, bReadWrite, is a value that indicates whether the method is reading or writing data: if TRUE the method reads data, if FALSE it writes data. The second parameter, pBuffer, is a void pointer to the buffer containing the data to be read from or written to, depending on the value of the bReadWrite flag. The pBuffer parameter points to the third parameter, bufferSize, which contains the buffer size in bytes. The fourth parameter, pReadWriteSize, is a pointer to an integer that takes as an output parameter the quantity of data actually read or written by the ISimpleStream::ReadWrite() method.
RRESULT ISimpleStream::Flush()
If the output stream on this stream is buffered, the ISimpleStream::Flush() method will ensure that all currently written data is applied to the stream.
RRESULT ISimpleStream::Peek()
The ISimpleStream::Peek() method should return S_OK if no more data is available to read on the stream, or E_FAIL if there is more data available. You may use Peek calls to ensure that client/server calls are in sync.
RRESULT ISimpleStream::IncRef()
RRESULT ISimpleStream::DecRef()
The ISimpleStream::IncRef() and ISimpleStream::DecRef() methods are used for reference counting. An application should call the ISimpleStream::IncRef() method whenever a reference to an ISimpleStream derived object is added, and ISimpleStream::DecRef() whenever a reference is removed. If the reference count for an ISimpleStream derived object reaches zero, the object should be deleted.
Attaching a Custom Network Protocol (Client Application)
Once the ISimpleStream derived class is compiled into a DLL, SO, or DYLIB dynamic library it must be loaded by the XStream HDVR client or server application.
The first step in loading an ISimpleStream class from a dynamic library is to specify the libraries that will be used for thick client (local server) and thin client (remote server). These libraries are specified in the HDRCCLIENT_CONFIGURATION_INFO structure. This structure has two fields: the HDRCCLIENT_CONFIGURATION_INFO::StreamPluginLocal field takes the name of the dynamic library containing the ISimpleStream based class that will be used for thick client streaming; the HDRCCLIENT_CONFIGURATION_INFO::StreamPluginRemote takes the name of the dynamic library that will be used for thin client streaming.
When the C++ client API is used, the HDRCCLIENT_CONFIGURATION_INFO structure is passed to the hdrcclientOpenLibraryEx2() function at the time the XStream HDVR library is initialized.
HDRCCLIENT_CONFIGURATION_INFO configInfo.
strcpy( configInfo.StreamPluginLocal, "hdrclocalstr.dll" );
strcpy( configInfo.StreamPluginRemote, "hdrcsockstr.dll" );
hdrcclientOpenLibraryEx2(HDRCCLIENT_SDK_VERSION, &pLibrary, &configInfo);
If using the Java/.NET client APIs, the HDRCCLIENT_CONFIGURATION_INFO structure is passed to the com.fovia.hdrcext.JNICalls.configureClient() method. This should be the first XStream HDVR method call in the application.
HDRCCLIENT_CONFIGURATION_INFO configInfo;
configInfo.StreamPluginLocal = "hdrclocalstr.dll";
configInfo.StreamPluginRemote = "hdrcsockstr.dll";
com.fovia.hdrcext.JNICalls.configureClient(configInfo);
Attaching a Custom Network Protocol (Server Application)
XStream HDVR server applications will by default make use of the built-in local and remote streaming classes provided by the XStream HDVR framework; however, the server can be directed to load user-defined plug-in DLLs that support a custom network protocol. To load custom plugin DLLs for local and remote streaming, create a file named hdrcopt.ini. This file contains fields that specify the path and file name of the local and remote plug-ins to be used for client/server communication.
; The hdrcopt.ini file.
[streamplugin]
path=/file_path/hdrcsockstr.dll
[streampluginlocal]
path=/file_path/hdrclocalstr.dll
