Using the Service Interface

# 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.