Wirbelscan service interface

Introduction

Do you want to talk with me?

wirbelscan implements, starting from version 0.0.5-pre12, a service interface, allowing other plugins to communicate with or control wirbelscan. The service interface can be implemented by including wirbelscans service header. You may also provide a copy of this header file in your source code, but pointing to wirbelscan is the preferred solution. 

#include "../wirbelscan/wirbelscan_services.h"
using namespace WIRBELSCAN_SERVICE;


virtual bool Service(const char *Id, void *Data = NULL);

Id is a unique identification string that identifies the plugin, the requested service and its protocol version number. A service id for wirbelscan looks like this: "wirbelscan_<SERVICE>#<VERSION>". At the moment of writing this, its assumed that higher versions will stay backward compatible, but in general, a plugin using the interface should use services only with matching service version.

NOTE: The function service returns true for any service id string it handles, and false otherwise.

The following services are available:

  • GetVersion, query wirbelscan plugin version and its service api
  • GetStatus, query wirbelscans status
  • DoCmd, execute commands
  • GetSetup, query actual setup parameters
  • SetSetup, change actual setup parameters
  • GetCountry, query list of country IDs and corresponding names
  • GetSat, query list of satellite IDs and corresponding names

    Data is a pointer to a data structure, depending on the service used. If Data is set to NULL and wirbelscan supports this service it will return true. You may use this as a 'service supported' check.

    GetVersion

    Query plugin and api, will work with every wirbelscan version supporting the interface.

    Id = "wirbelscan_GetVersion".
    Data is a pointer of type cWirbelscanInfo.

    GetStatus

    Query actual status.

    Id = "wirbelscan_GetStatus#<VERSION>".
    Data is a pointer of type cWirbelscanStatus.

    The following properties are returned in version 0001:

  • Status {scanning,stopped,busy,unknown}
  • Current Scan device
  • Current Scan Progress
  • Current Signal Strength as reported from device.
  • Currently Scanned Transponder
  • Number of Channels in VDR
  • Number of New Channels since Scan Start

    • NOTE: Most of the properties are meaningless, if no scan in progress.

    DoCmd

    Execute commands.

    Id = "wirbelscan_DoCmd#<VERSION>".
    Data is a pointer of type cWirbelscanCmd.

    Data->replycode will be true on success, false otherwise.
    The following commands are defined in version 0001:

  • Start Scan
  • Stop Scan
  • Store Current Setup

    • GetSetup

    Query actual setup parameters.

    Id = "wirbelscan_GetSetup#<VERSION>".
    Data is a pointer of type cWirbelscanScanSetup.

    SetSetup

    Change actual setup parameters.

    Id = "wirbelscan_SetSetup#<VERSION>".
    Data is a pointer of type cWirbelscanScanSetup.

    NOTE: The changes will be only permanent, if the command Store is called afterwards, see DoCmd.

    GetCountry

    Query list of country IDs and corresponding names.
    The ID is needed for wirbelscans Setup in case of DVB-C, DVB-T, ATSC or pvrinput scans. With wrong setup ID values scans are expected to fail, so the setup CountryId has to be set before starting a scan.

    Id = "wirbelscan_GetCountry#<VERSION>".
    Data is a pointer of type cPreAllocBuffer.

    Should be called twice.

  • first call with Data->size = 0. wirbelscan will initialize Data->size to minimum buffer size.
  • second call, this time Data->buffer should point to allocated memory of size * sizeof(SListItem). wirbelscan will fill in values.

    NOTE: It's the calling plugins responsibility to provide a buffer of sufficient size and to cleanup this buffer. If the provided buffer is too small, segmentation fault / memory corruption will occur.

    GetSat

    Query list of satellite IDs and corresponding names.
    The ID is needed for wirbelscans Setup in case of satellite scans. With wrong setup ID values scans are expected to fail, so the setup SatId has to be set before starting a scan.

    Id = "wirbelscan_GetSat#<VERSION>".
    Data is a pointer of type cPreAllocBuffer.

    Should be called twice.

  • first call with Data->size = 0. wirbelscan will initialize Data->size to minimum buffer size.
  • second call, this time Data->buffer should point to allocated memory of size * sizeof(SListItem). wirbelscan will fill in values.

    NOTE: It's the calling plugins responsibility to provide a buffer of sufficient size and to cleanup this buffer. If the provided buffer is too small, segmentation fault / memory corruption will occur.

    Further Information

    An example on usage is the servdemo plugin, available on the wirbelscan webpage. This demo plugin takes SVDRP commands and talks to wirbelscan using the service interface.

    For further details, please refer to VDRs PLUGIN.html and wirbelscan_services.h.