Using a DSP objectCreating a DSP object
The Distributed Scripting Protocol provides no internal method for managing a connection or transporting packets. It is simply a framework, with the physical transport method being supplied by the user. As such, it is impossible to simply create a DSP object, because it is incapable of doing anything by itself. The user must supply a set of functions to manage the connection with the server. To create a DSP object, you call new DSP(myOpenFunction, myParameters). The function that you supply must open the connection and return a reference to it. It is possible in some instances that you do not need to open anything special, and so you can ignore this parameter. Here is an example of an open function for a DSP connection, using internet sockets:
function idspOpen( host, port )
{
return new Socket( host, port );
}
We will see this function passed to the DSP constructor in a moment. First, to accomplish sending/receiving packets, the user needs to define two functions, dspSend and dspReceive. These functions must be inherited through the prototype chain, because otherwise when DSP objects are copied implicitly through reference construction (see below), the functions will not get passed. Because we want to keep the DSP functions (such as dspService), we need to preserve the original DSP prototype, and a constructor looks like the following:
function iDSP( host, port )
{
var ret = new DSP( idspOpen, host, port );
// Now we override the ._prototype to insert our functions
if( ret != null )
ret._prototype = iDSP.prototype;
return ret;
}
// Here we set up the iDSP.prototype to keep the DSP functions
// in the chain
iDSP.prototype._prototype = DSP.prototype;
Once this constructor is called, we have a valid DSP object, assuming we add the transport functions. To do this, we must add dspSend and dspReceive to the prototype. The actual syntax of these functions is similar to Clib.fread() and Clib.fwrite(), and a description can be found in the function reference. For our iDSP example, they would look something like this:
function iDSP.prototype.dspSend( conn, buffer, timeout )
{ // Ignore timeout
return conn.write(buffer);
}
function iDSP.prototype.dspReceive( conn, &buffer, length, timeout)
{
return conn.read( buffer, length );
}
Note that both these functions ignore the timeout parameter and do not correctly handle errors. A full-featured version of these functions can be found in the file idsp.jsh. The final function that we must provide is the dspCloseConnection function, which is responsible for closing the connection. This function looks like the following:
function iDSP.prototype.dspCloseConnection( conn )
{
conn.close();
}
Once all of these transport functions have been defined, new iDSP objects can be instantiated with a call to new iDSP and used as any other DSP object. Because the transport level of DSP is separate from the core library, DSP can be adapted to communicate between any servers in any way. In addition, communication can be done during the call to the open function. This allows for password authentication or any other information to be shared.