Revision as of 17:28, 18 September 2021

Services API V2 Conversion

Conversion Process

We are creating a new copy of everything in programs/mythbackend/servicesv2/. Eventually we will delete the original code once all is working.

Convert Service

Start by converting the main service files (e.g. Video Service).

• copy service header and cpp from programs/mythbackend/services/ to servicesv2 and add v2 in front of file names and V2 in front of class names.
• Service class must be based on MythHTTPService instead of abstract base class called xxxServices.
• in the header file is there is no version defined, add one , e.g.

  Q_CLASSINFO("Version","1.0")

• Add methods as follows to the header file

  public:
    V2Dvr();
   ~V2Dvr() override = default;
    static void RegisterCustomTypes();
  private:
    Q_DISABLE_COPY(V2Dvr)

• Add to service cpp file with appropriate changes, see v2video for example

Q_GLOBAL_STATIC_WITH_ARGS(MythHTTPMetaService, s_service,
(VIDEO_HANDLE, V2Video::staticMetaObject, std::bind(&V2Video::RegisterCustomTypes)))

• Add to service cpp

void V2Video::RegisterCustomTypes()

in there you will add for each return type from a service that is not an elementary item or Qt class

qRegisterMetaType<V2VideoMetadataInfo*>("V2VideoMetadataInfo");

• Add constructor like this

V2Video::V2Video() : MythHTTPService(s_service) {}

• Add to mythbackend/main_helpers.cpp, with the similar items:

MythHTTPInstance::Addservices({{ VIDEO_SERVICE, &MythHTTPService::Create<V2Video> }});

• If the header file includes class ScriptableGuide : public QObject, delete that entire class.

Convert Methods

I suggest copy one method at a time and test.

• copy header files from libs/libmythservicecontracts/datacontracts/ and add v2 in front of file names and V2 in front of class names
• Copy functions from serviceutil to v2serviceutil as needed - put v2 in front of function or class names
• fix #ifndef and #define in header files to new file names
• Remove these two

#include "serviceexp.h"
#include "datacontracthelper.h"

Replace them with

#include "libmythbase/http/mythhttpservice.h" 

• Change "version" to "Version" in Q_CLASSINFO
• service methods must be in public slots.
• Remove namespace DTC
• Remove DTC:: and Add V2 in front of class names
• Remove SERVICE_PUBLIC
• Remove Q_PROPERTY for int, QString, QDate, QVariantList types, as longs as there are PROPERTYIMP lines for them.
• PROPERTYIMP_ENUM - if it outputs an integer corresponding to the enum, you can change it to SERVICE_PROPERTY2 and change the type to int instead of the enum type.
• Leave Q_PROPERTY for QObject* entries and move them to between the SERVICE_PROPERTY lines. Also add USER true to the entry.
• Change PROPERTYIMP, PROPERTYIMP_REF, PROPERTYIMP_RO_REF - change to SERVICE_PROPERTY2
• Change PROPERTYIMP_PTR to SERVICE_PROPERTY_PTR
• Remove static inline void InitializeCustomTypes() and its implementation
• Add Q_DECLARE_METATYPE(V2VideoMetadataInfo*) for each class used in return messages
• Add Q_INVOKABLE to constructors of classes used in return messages.
• Where SERVICE_PROPERTY2 has a QVariantList you need a line, which should already be there, fix the class name with the V2 in front:

Q_CLASSINFO( "VideoMetadataInfos", "type=V2VideoMetadataInfo");

• Add to the service class void V2xxxx::RegisterCustomTypes(), for every type that is the main structure returned from a service:

qRegisterMetaType<V2VideoMetadataInfo*>("V2VideoMetadataInfo")

• Add header files to mythbackend.pro
• If method is not "Get" or "Set" you need to supply the methods in the header file in the class

Q_CLASSINFO("SendMessage", "methods=GET,POST,HEAD")

Normally Methods are GET,POST,HEAD or POST

• To change the name of the return top level name in xml (for compatibility with old services that return something like <long>123</long>):

Q_CLASSINFO("GetSavedBookmark",  "name=long")
Q_CLASSINFO("GetContextList",   "name=StringList")

• If you need to use both methods and name in Q_CLASSINFO, then separate with a semicolon

Q_CLASSINFO("GetSavedBookmark",  "methods=GET,POST,HEAD;name=long")

• When you find code that checks for presence of parameters like this:

if (m_parsedParams.contains("title"))

change to this. This is an existing macro with the old system that has been updated to work with v2:

if (HAS_PARAM("title"))

Testing

To see error messages as to why a method is failing with a 404 run mythbackend with -v http. Also using: mythbackend --setverbose http[:debug] allows changing logging 'on-the-fly', so restarting the backend isn't required. Use http:alert to turn that logging off.

Difference Tracking

During the conversion, differences between the original API and V2 will be kept here. These may be removed prior to the next release of MythTV (v32).

$ curl ofc0.local:6544/Myth/GetHosts
<?xml version="1.0" encoding="UTF-8"?><StringList><String>lt0</String><String>ofc0</String></StringList>
curl ofc0.local:6744/Myth/GetHosts
<?xml version="1.0" encoding="UTF-8"?><StringList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" serializerVersion="1.1"><String>lt0</String><String>ofc0</String> 
</StringList>

Capture Service API List (8)

Channel Service API List (15)

Content Service API List (22)

I did not convert live streaming methods as they are complex and I do not have a way of testing them. I recommend they be deprecated since they appear to need proprietary software to play the live stream.

Dvr Service API List (51)

Frontend Service API List

Guide Service API List (9)

Image Service API List (8)

Music Service API List (2)

Myth Service API List (32)

Video Service API List (12)

Status Service API List