Services API V2 Conversion

From MythTV Official Wiki
Revision as of 22:12, 14 October 2021 by Llib (talk | contribs) (Add two differences)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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>
GetFormatTime (not working in V1 or V2)
V1 {'String': }
V2 {'String': None}
PutSetting:
V1 {'bool': 'true'}
V2 {'bool': True}

Capture Service API List (8)

API Command POST Required? Description Developer Status Notes
AddCaptureCard Yes Add a brand new capture device to the database. Peter Bennett Complete
AddCardInput Yes Add a new card input to the database, and associate it with a video listings source. Peter Bennett Complete
GetCaptureCard No Get info on a specific capture device, by card id. Peter Bennett Complete
GetCaptureCardList No Get a list of configured capture devices globally, on a certain host, or of a certain type. Peter Bennett Complete
RemoveCaptureCard Yes Remove a particular capture device from the database, by card id. Peter Bennett Complete
RemoveCardInput Yes Remove a particular card input from the database, by card input id. Peter Bennett Complete This is identical to RemoveCaptureCard except for parameter name. Should it be deprecated?
UpdateCaptureCard Yes Change a specific setting value for a specific capture device. Peter Bennett Complete
UpdateCardInput Yes Change a specific setting value for a specific card input id. Peter Bennett Complete This is identical to UpdateCaptureCard except for parameter name. Should it be deprecated?

Channel Service API List (15)

API Command POST Required? Description Developer Status Notes
AddDBChannel Yes Add a new channel to the database. Peter Bennett Complete
AddVideoSource Yes Add a new video source. Peter Bennett Complete
FetchChannelsFromSource No Get a list of channels for a specific source. Peter Bennett Complete
GetChannelInfo No Get info on a specific channel. Peter Bennett Complete
GetChannelInfoList No Get a list of configured channels. Peter Bennett Complete
GetDDLineupList No Get Data Direct lineup. Peter Bennett Complete
GetVideoMultiplex No Get the video multiplexes for a specific multiplex ID. Peter Bennett Complete
GetVideoMultiplexList No Get a list of all video multiplexes. Peter Bennett Complete
GetVideoSource]] No Get individual video source. Peter Bennett Complete
GetVideoSourceList No Get all video sources. Note, usernames/passwords are included. Peter Bennett Complete
GetXMLTVIdList No Get a list of XMLTVIDs for a given source ID. Peter Bennett Complete
RemoveDBChannel Yes Remove a particular channel from the database. Peter Bennett Complete
RemoveVideoSource Yes Remove a specific video source. Peter Bennett Complete
UpdateDBChannel Yes Update a specific channel's database information. Peter Bennett Complete
UpdateVideoSource Yes Change a specific setting value for a specific video source. Peter Bennett Complete

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.

API Command POST Required? Description Developer Status Notes
AddLiveStream No Start a HTTP Live Stream transcode for a given file and storage group. Not started
AddRecordingLiveStream No Start a HTTP Live Stream transcode for a given ChanId and StartTime. Not Started
AddVideoLiveStream No Start a HTTP Live Stream transcode for a given Video ID. Not started
DownloadFile Yes Instruct the backend to download a remote file into a storage group. Peter Bennett Complete
GetAlbumArt No Display, and optionally scale, the album art for a given music file's database id number. Peter Bennett Complete
GetDirList No Get a list of directories Peter Bennett Complete
GetFile No Download a given file from a given storage group. Peter Bennett Complete
GetFileList No Get a list of files in a specified storage group. Peter Bennett Complete
GetHash No Perform a unique identifying hash on a given file in a given storage group. Peter Bennett Complete
GetImageFile No Display, and optionally scale, an image file from a given storage group. Peter Bennett Complete
GetLiveStream No Get the stream status data for a given HTTP Live Stream. Not Started
GetLiveStreamList No Get the stream status data for all available HTTP Live Streams. Not started
GetMusic No Download a given music file by database id. Peter Bennett Complete
GetPreviewImage No Display, and optionally scale, an preview thumbnail for a given recording by timestamp, chanid and starttime. Peter Bennett Complete
GetProgramArtworkList No Display a list of artwork available for a program by inetref and season. Peter Bennett Complete
GetRecording No Download a given recording file by chanid and starttime. Peter Bennett Complete
GetRecordingArtwork No Display, and optionally scale, an image file of a given type (coverart, banner, fanart) for a given recording's inetref and season number. Peter Bennett Complete
GetRecordingArtworkList No Display a list of artwork available for a recording by start time and channel id. Peter Bennett Complete
GetVideo No Download a given video by database id. Peter Bennett Complete
GetVideoArtwork No Display, and optionally scale, an image file of a given type (coverart, banner, fanart) for a given video's database id number. Peter Bennett Complete
RemoveLiveStream No Stop transcoding a given HTTP Live Stream, and remove the transcoded files. Not started
StopLiveStream No Stop transcoding a given HTTP Live Stream, leaving the transcoded files intact. Not Started

Dvr Service API List (51)

API Command Service Version POST Required? Description Developer Status Notes
AddDontRecordSchedule  ? No TBC Peter Bennett Complete
AddRecordSchedule  ? Yes Add a single recording rule, by record id. Peter Bennett Complete
AddRecordedCredits 7.0 Yes Add credits to a currently recorded program. Peter Bennett Complete
AddRecordedProgram 7.0 Yes Add a recorded program entry into MythTV. Peter Bennett Complete
AllowReRecord  ? No TBC Peter Bennett Complete
DeleteRecording 6.0 Yes Delete a recording, by recording id Peter Bennett Complete
DisableRecordSchedule  ? Yes Disable a recording schedule, by record id. Peter Bennett Complete
DupInToDescription  ? No TBC Peter Bennett Complete
DupInToString  ? No TBC Peter Bennett Complete
DupMethodToDescription  ? No TBC Peter Bennett Complete
DupMethodToString  ? No TBC Peter Bennett Complete
EnableRecordSchedule  ? Yes Enable a recording schedule, by record id. Peter Bennett Complete
GetConflictList  ? No Query information on upcoming items which will not record due to conflicts. Peter Bennett Complete
GetEncoderList  ? No Query information on configured capture devices, and their current activity. Peter Bennett Complete
GetExpiringList  ? No Query information on recorded programs which are set to expire. Peter Bennett Complete
GetInputList  ? No TBC Peter Bennett Complete
GetOldRecordedList  ? No TBC Peter Bennett Complete
GetPlayGroupList  ? No TBC Peter Bennett Complete
GetProgramCategories  ? No TBC Peter Bennett Complete
GetRecGroupList  ? No TBC Peter Bennett Complete
GetRecRuleFilterList  ? No TBC Peter Bennett Complete
GetRecStorageGroupList  ? No TBC Peter Bennett Complete
GetRecordSchedule  ? No Return a single recording rule, by record id. Peter Bennett Complete
GetRecordScheduleList  ? No Query all configured recording rules, and return them in a list. Peter Bennett Complete
GetRecorded  ? No Query information on a single item from recordings. Peter Bennett Complete
GetRecordedCommBreak  ? No TBC Peter Bennett Complete
GetRecordedCutList  ? No TBC Peter Bennett Complete
GetRecordedList  ? No Query information on all recorded programs. Peter Bennett Complete
GetRecordedMarkup 7.0 No Retrieve the complete markup and seek tables by Recorded Id Peter Bennett Complete
GetRecordedSeek 6.3 No Retrieve the seektable, by recording id and type Peter Bennett Complete
GetSavedBookmark  ? No TBC Peter Bennett Complete
GetTitleInfoList  ? No TBC Peter Bennett Complete
GetTitleList  ? No TBC Peter Bennett Complete
GetUpcomingList  ? No Query information on all upcoming programs matching recording rules. Peter Bennett Complete
ManageJobQueue 6.6 Yes Administer User, Commflag and Metadata jobs Peter Bennett Complete
ReactivateRecording 6.3 No Reactivate a stopped recording, by recording id Peter Bennett Complete
RecStatusToDescription  ? No TBC Peter Bennett Complete
RecStatusToString  ? No TBC Peter Bennett Complete
RecTypeToDescription  ? No TBC Peter Bennett Complete
RecTypeToString  ? No TBC Peter Bennett Complete
RecordedIdForKey  ? No TBC Peter Bennett Complete
RecordedIdForPathname  ? No TBC Peter Bennett Complete
RemoveRecordSchedule  ? Yes Remove a Recording rule. Peter Bennett Complete
RemoveRecorded  ? Yes Delete a Recording (deprecated, replaced by DeleteRecording in later versions) Peter Bennett Complete
RescheduleRecordings 6.3 No Trigger a reschedule Peter Bennett Complete
SetRecordedMarkup 7.0 Yes Set the markup and seek tables for the given Recorded Id Peter Bennett Complete
SetSavedBookmark  ? No TBC Peter Bennett Complete
StopRecording 6.3 No Stop a current recording, by recording id Peter Bennett Complete
UnDeleteRecording 6.0 Yes Un-delete a recording, by recording id Peter Bennett Complete
UpdateRecordSchedule  ? Yes Update a single recording rule, by record id. Peter Bennett Complete
UpdateRecordedWatchedStatus 6.0 Yes Mark a recording watched, or unwatched, by recording id Peter Bennett Complete

Frontend Service API List

API Command POST Required? Description Developer Status Notes
GetStatus No Get the location, playback status, and a variety of other information about the current state of the Frontend. Mark Kendall [0f8333b68c] Complete
SendMessage No (Yes 0.28+) Send a message to the frontend, which will appear as a popup message on the screen. Mark Kendall [0f8333b68c] Complete
SendNotification No (Yes 0.28+) Send a notification to the frontend which will appear in the Notification Center. Mark Kendall [0f8333b68c] Complete
SendAction No (Yes 0.28+) Send an action such as UP, DOWN, SELECT, etc. to the frontend. Mark Kendall [0f8333b68c] Complete
GetActionList No Get a list of actions which can be performed on the frontend using SendAction. Mark Kendall [0f8333b68c] Complete
PlayRecording No (Yes 0.28+) Play a television recording. Mark Kendall [0f8333b68c] Complete
PlayVideo No (Yes 0.28+) Play a video. Mark Kendall [0f8333b68c] Complete
SendKey Yes (new in 0.28+) Send a window aware key such as UP, DOWN, SELECT, etc. to the frontend. Mark Kendall [0f8333b68c] Complete

Guide Service API List (9)

API Command POST Required? Description Developer Status Notes
AddToChannelGroup Yes Add a given channel to a channel group. Peter Bennett Complete
GetCategoryList No Get a list of program categories. Peter Bennett Complete
GetChannelGroupList No Get the list of channel groups. Peter Bennett Complete
GetChannelIcon No Get the icon file for a given channel. Peter Bennett Complete
GetProgramDetails No Get the detailed guide information for a particular program starting at a particular time on a particular channel. Peter Bennett Complete
GetProgramGuide No The the guide information for a particular time period and set of channels Peter Bennett Complete
GetProgramList No Get a filtered list of programs matching the given search criteria. Peter Bennett Complete
GetStoredSearches No Get the list of stored searches. Peter Bennett Complete
RemoveFromChannelGroup Yes Remove a given channel from a channel group. Peter Bennett Complete

Image Service API List (8)

API Command POST Required? Description Developer Status Notes
CreateThumbnail Yes TBC Peter Bennett Abandoned Image Services do not work
GetImageInfo No TBC Peter Bennett Abandoned Image Services do not work
GetImageInfoList No TBC Peter Bennett Abandoned Image Services do not work
GetSyncStatus No TBC. Peter Bennett Abandoned Image Services do not work
RemoveImage Yes TBC. Peter Bennett Abandoned Image Services do not work
RenameImage Yes TBC. Peter Bennett Abandoned Image Services do not work
StartSync Yes TBC. Peter Bennett Abandoned Image Services do not work
StopSync Yes TBC. Peter Bennett Abandoned Image Services do not work

Music Service API List (2)

API Command POST Required? Description Developer Status Notes
GetTrack No Gets metadata for an individual music track Peter Bennett Complete
GetTrackList No Gets metadata for all music tracks Peter Bennett Complete

Myth Service API List (32)

API Command POST Required? Description Developer Status Notes
AddStorageGroupDir Yes Adds one storage group bill6502 Completed
BackupDatabase Yes Backup the mythconverg DB bill6502 Completed
ChangePassword Yes Change the API user's password bill6502 Was deprecated, now deleted.
CheckDatabase Yes Run mysqlcheck or optionally mysql repair on mythconverg bill6502 Completed
DelayShutdown Yes (new in v31) Delay backend shutdown for 5 minutes bill6502 Completed
GetBackendInfo No (new in 0.28) Get basic information about the backend's configuration. Peter Bennett Completed
GetConnectionInfo No Gets config.xml information bill6502 Completed
GetFormatDate No TBA bill6502 Completed
GetFormatDateTime No TBA bill6502 Completed
GetFormatTime No TBA bill6502 Completed
GetFrontends No TBA bill6502 Completed
GetHostName No Host name used as a profile name in settings etc. bill6502 Completed
GetHosts No All hosts known to the backend bill6502 Completed
GetKeys No Returns all value columns in settings bill6502 Completed
GetLogs No Get backend logs from the DB Peter Bennett Completed
GetSetting No Gets an individual setting in 0.28+ bill6502 Completed
GetSettingList No Gets a list of settings in 0.28+ Peter Bennett Completed
GetStorageGroupDirs No Get one storage group's directory information Peter Bennett Completed
GetTimeZone No Get the current time zone information bill6502 Completed
ManageDigestUser (v30+) Yes Add/Remove/ChangePassword for API users bill6502 Complete
ManageUrlProtection (v30+) Yes Setup digest protection for none, one or more services bill6502 Deprecated May be removed in v33
ParseISODateString No TBA bill6502 Completed
ProfileDelete align="center" | Yes Delete smolt profile bill6502 Completed
ProfileSubmit Yes Send MythTV profile to smolt bill6502 Completed
ProfileText Yes TBA bill6502 Completed
ProfileURL Yes TBA bill6502 Completed
ProfileUpdated No TBA bill6502 Completed
PutSetting Yes Add a new entry in the mythconverg.settings table bill6502 Completed
RemoveStorageGroupDir Yes Remove one storage directory bill6502 Completed
SendMessage No (0.28+ Yes) Send a message to one or more frontends, which will appear as a popup message on the screen. bill6502 Completed
SendNotification No (0.28+ Yes) Send a notification to one or more frontends which will appear in the Notification Center. bill6502 Completed
TestDBSettings Yes starts mysqlcheck or optionally repair bill6502 Completed

Video Service API List (12)

API Command POST Required? Description Developer Status Notes
AddVideo Yes Add a new filename to the video database. Peter Bennett Complete
GetBluray No Query technical data for a Blu-ray disc or folder. Peter Bennett Complete
GetSavedBookmark No Get a saved bookmark for a video. Peter Bennett [3ee9b7ed77] Complete
GetStreamInfo No Get frame rate, frame size, etc. for a video or recording Peter Bennett Complete
GetVideo No Get a single video's metadata by database id. Peter Bennett [cff3f63562] Complete
GetVideoByFileName No Get a single video's metadata by filename. Peter Bennett [3ee9b7ed77] Complete
GetVideoList No Get a list of videos and their metadata. Peter Bennett [b05bec6c73] Complete
LookupVideo No Perform an online metadata lookup for a given title, subtitle, inetref, season, or episode number. Peter Bennett Complete
RemoveVideoFromDB Yes Remove a single video from the database by database id. Peter Bennett Complete
SetSavedBookmark Yes Save a bookmark for a video Peter Bennett Complete
UpdateVideoMetadata Yes Updates the metadata of a video Peter Bennett Complete
UpdateVideoWatchedStatus Yes Update the watched flag for a video Peter Bennett Complete

Status Service API List

API Command POST Required? Description Developer Status Notes
Status No Get Backend Status in HTML Peter Bennett Complete Predates Services API. Returns only HTML
GetStatusHTML No Get Backend Status in HTML Peter Bennett Complete Predates Services API. Returns only HTML
GetStatus No Get Backend Status in XML Peter Bennett Complete Predates Services API. Returns only XML
xml No Get Backend Status in XML Peter Bennett Complete Predates Services API. Returns only XML