DSSCTRL - Control You DSS Receiver

To generate documentation, run "make doc" on the command line (after running the configure script successfully). The makefile generate complate API documentation in the directory doc/HTML. Note that doxygen must be installed.

Using the libdssctrl library is fairly straight forward. Central to using the libdssctrl library is the opaque structure S_DSSCtrl which defines a connection to a remote dssctrld server.

Open a connection to a dssctrld server using the call:

    S_DSSCtrl *DSSCtrl_Connect(const char *Server_Name, int Port, unsigned long Timeout);
              

The Server_Name is the name of the server on the network. The name may either be a dotted quad address ( such as 192.168.0.10) or a fully qualified name (such as mythtv.home.net).

The Port is the port that the dssctrld server is listening to. The default port may be specified by using the #define DSSCTRL_DEFAULT_PORT.

The Timeout is the time (in mSec) that the client should wait for a response from the server before failing a request in error. A good typical value would be 30000 (30 seconds).

A NULL pointer is returned on error.

Once a connection is open, zero or more commands may be issued to the server. The calls below may be used to issue various commands to the server:

     int DSSCtrl_Set_Device(S_DSSCtrl *DSSCtrl, unsigned Device_Number);
     int DSSCtrl_Get_Device(S_DSSCtrl *DSSCtrl, unsigned *Device_Number);
     int DSSCtrl_Get_State(S_DSSCtrl *DSSCtrl, int *State);
     int DSSCtrl_Power_On(S_DSSCtrl *DSSCtrl);
     int DSSCtrl_Power_Off(S_DSSCtrl *DSSCtrl);
     int DSSCtrl_Set_Channel(S_DSSCtrl *DSSCtrl, unsigned Channel);
     int DSSCtrl_Get_Channel(S_DSSCtrl *DSSCtrl, unsigned *Channel);
     int DSSCtrl_Get_Time(S_DSSCtrl *DSSCtrl, time_t *Time);
     int DSSCtrl_Get_Signal_Strength(S_DSSCtrl *DSSCtrl, float *Signal_Strength);
     int DSSCtrl_Display_Message(S_DSSCtrl *DSSCtrl, const char *Text);
              

All the functions above should be self explanatory. Note that the functions above return 0 on success.

If a particular device does not support the requested operation, the request terminated on error (a non-zero value is returned).

Lastly, be sure to close the connection using the call:

     void DSSCtrl_Disconnect(S_DSSCtrl *DSSCtrl);
              

For more details, look at the doxygen generated API documentation and the source to the dssctrl client in the dssctrl subdirectory.

The dssctrld server has been designed to be fairly modular, making the task of adding support for new devices fairly straight forward.

Create an ANSI c source file and associated header file giving it the name of the device type you plan to use on the command line. In this file, define a static instance of the structure S_Device_Type (as defined in device.h) which contains the device name and pointers to the functions to be called to perform each task. Also include the source code for each function that can be implemented that is required by the S_Device_Type. If a facility can not be implemented, then use a NULL pointer in the S_Device_Type instance.

To actually add the device to the dssctrld server, add a pointer to your structure to the Device_Types array in device_types.c. Also be sure to add your source file (ANSI c) to the Makefile.am in the dssctrld subdirectory.

For an example, look at the files rca.h and rca.c in the dssctrld subdirectory.

If you add support for a new device, please feel free to send us a patch (or even a tarball of your source). We'll add your work the project and credit you for your addition.

If you would like to contribute to the development of dssctrl, please feel free to contact a member of the project team. We do ask that one patch that you submit be included into the source prior to being given write access to CVS repository.

If you submit patches that change existing files, we ask that you make a best effort to follow the coding style in the files that you modify. If you create new files, you may follow almost any coding style you like provided:

1. You comment your code to support doxygen.
2. You don't use tabs, or you always remove tabs prior to adding entries to the repository.
3. You don't use hungarian notation.