Difference between revisions of "Services API V2 Conversion"

From MythTV Official Wiki
Jump to: navigation, search
(Relocate difference tracking, green Myth completed)
(Convert Methods: How to convert m_parsedParams)
Line 49: Line 49:
 
* If you need to use both methods and name in Q_CLASSINFO, then separate with a semicolon
 
* If you need to use both methods and name in Q_CLASSINFO, then separate with a semicolon
 
<pre>Q_CLASSINFO("GetSavedBookmark",  "methods=GET,POST,HEAD;name=long")</pre>
 
<pre>Q_CLASSINFO("GetSavedBookmark",  "methods=GET,POST,HEAD;name=long")</pre>
 +
* When you find code that checks for presence of parameters like this:
 +
<pre>if (m_parsedParams.contains("title"))</pre>
 +
Then add this before the check (replacing UpdateVideoMetadata with the name of the method):
 +
<pre>
 +
// Find the method parameters
 +
HTTPMethodPtr handler = nullptr;
 +
for (auto & [path, handle] : m_staticMetaService->m_slots)
 +
    if (path == "UpdateVideoMetadata") { handler = handle; break; }
 +
 +
if (handler == nullptr)
 +
{
 +
    LOG(VB_GENERAL, LOG_ERR, QString("UpdateVideoMetadata: handler not found"));
 +
    return false;
 +
}
 +
 +
auto names  = handler->m_names;
 +
</pre>
 +
Replace the check with:
 +
<pre>if (arrayContains(names,"title"))</pre>
 +
 
==== Testing ====
 
==== Testing ====
 
To see error messages as to why a method is failing with a 404 run mythbackend with -v http.
 
To see error messages as to why a method is failing with a 404 run mythbackend with -v http.

Revision as of 19:34, 1 July 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.
  • 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) {}

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" 
  • 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.
  • Leave Q_PROPERTY for QObject* entries
  • Change PROPERTYIMP, PROPERTYIMP_REF, PROPERTYIMP_RO_REF - change to SERVICE_PROPERTY2
  • Remove static inline void InitializeCustomTypes() and its implementation
  • Add Q_DECLARE_METATYPE(V2VideoMetadataInfo*) for each class used in return messages
  • Remove Q_INVOKABLE from comstructors
  • 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"))

Then add this before the check (replacing UpdateVideoMetadata with the name of the method):

// Find the method parameters
HTTPMethodPtr handler = nullptr;
for (auto & [path, handle] : m_staticMetaService->m_slots)
    if (path == "UpdateVideoMetadata") { handler = handle; break; }

if (handler == nullptr)
{
    LOG(VB_GENERAL, LOG_ERR, QString("UpdateVideoMetadata: handler not found"));
    return false;
}

auto names  = handler->m_names;

Replace the check with:

if (arrayContains(names,"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)

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

Channel Service API List (15)

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

Content Service API List (22)

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. Not Started
GetAlbumArt No Display, and optionally scale, the album art for a given music file's database id number. Not Started
GetDirList No Get a list of directories Not Started
GetFile No Download a given file from a given storage group. Not started
GetFileList No Get a list of files in a specified storage group. Not started
GetHash No Perform a unique identifying hash on a given file in a given storage group. Not started
GetImageFile No Display, and optionally scale, an image file from a given storage group. Not Started
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. Not started
GetPreviewImage No Display, and optionally scale, an preview thumbnail for a given recording by timestamp, chanid and starttime. Not started
GetProgramArtworkList No Display a list of artwork available for a program by inetref and season. Not Started
GetRecording No Download a given recording file by chanid and starttime. Not Started
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. Not Started
GetRecordingArtworkList No Display a list of artwork available for a recording by start time and channel id. Not started
GetVideo No Download a given video by database id. Not Started
GetVideoArtwork No Display, and optionally scale, an image file of a given type (coverart, banner, fanart) for a given video's database id number. Not started
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 Not started
AddRecordSchedule  ? Yes Add a single recording rule, by record id. Not started
AddRecordedCredits 7.0 Yes Add credits to a currently recorded program. Not Started
AddRecordedProgram 7.0 Yes Add a recorded program entry into MythTV. Not started
AllowReRecord  ? No TBC Not Started
DeleteRecording 6.0 Yes Delete a recording, by recording id Not Started
DisableRecordSchedule  ? Yes Disable a recording schedule, by record id. Not started
DupInToDescription  ? No TBC Not started
DupInToString  ? No TBC Not Started
DupMethodToDescription  ? No TBC Not started
DupMethodToString  ? No TBC Not Started
EnableRecordSchedule  ? Yes Enable a recording schedule, by record id. Not Started
GetConflictList  ? No Query information on upcoming items which will not record due to conflicts. Not Started
GetEncoderList  ? No Query information on configured capture devices, and their current activity. Not Started
GetExpiringList  ? No Query information on recorded programs which are set to expire. Not started
GetInputList  ? No TBC Not started
GetOldRecordedList  ? No TBC Not Started
GetPlayGroupList  ? No TBC Not started
GetProgramCategories  ? No TBC Not Started
GetRecGroupList  ? No TBC Not started
GetRecRuleFilterList  ? No TBC Not Started
GetRecStorageGroupList  ? No TBC Not started
GetRecordSchedule  ? No Return a single recording rule, by record id. Not started
GetRecordScheduleList  ? No Query all configured recording rules, and return them in a list. Not Started
GetRecorded  ? No Query information on a single item from recordings. Not started
GetRecordedCommBreak  ? No TBC Not Started
GetRecordedCutList  ? No TBC Not started
GetRecordedList  ? No Query information on all recorded programs. Not Started
GetRecordedMarkup 7.0 No Retrieve the complete markup and seek tables by Recorded Id Not started
GetRecordedSeek 6.3 No Retrieve the seektable, by recording id and type Not started
GetSavedBookmark  ? No TBC Not started
GetTitleInfoList  ? No TBC Not Started
GetTitleList  ? No TBC Not started
GetUpcomingList  ? No Query information on all upcoming programs matching recording rules. Not Started
ManageJobQueue 6.6 Yes Administer User, Commflag and Metadata jobs Not Started
ReactivateRecording 6.3 No Reactivate a stopped recording, by recording id Not Started
RecStatusToDescription  ? No TBC Not Started
RecStatusToString  ? No TBC Not started
RecTypeToDescription  ? No TBC Not Started
RecTypeToString  ? No TBC Not started
RecordedIdForKey  ? No TBC Not Started
RecordedIdForPathname  ? No TBC Not started
RemoveRecordSchedule  ? Yes Remove a Recording rule. Not started
RemoveRecorded  ? Yes Delete a Recording (deprecated, replaced by DeleteRecording in later versions) Not started
RescheduleRecordings 6.3 No Trigger a reschedule Not started
SetRecordedMarkup 7.0 Yes Set the markup and seek tables for the given Recorded Id Not Started
SetSavedBookmark  ? No TBC Not Started
StopRecording 6.3 No Stop a current recording, by recording id Not started
UnDeleteRecording 6.0 Yes Un-delete a recording, by recording id Not started
UpdateRecordSchedule  ? Yes Update a single recording rule, by record id. Not started
UpdateRecordedWatchedStatus 6.0 Yes Mark a recording watched, or unwatched, by recording id Not Started

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. Not Started
GetCategoryList No Get a list of program categories. Not Started
GetChannelGroupList No Get the list of channel groups. Not started
GetChannelIcon No Get the icon file for a given channel. Not started
GetProgramDetails No Get the detailed guide information for a particular program starting at a particular time on a particular channel. Not Started
GetProgramGuide No The the guide information for a particular time period and set of channels Not started
GetProgramList No Get a filtered list of programs matching the given search criteria. Not Started
GetStoredSearches No Get the list of stored searches. Not started
RemoveFromChannelGroup Yes Remove a given channel from a channel group. Not started

Image Service API List (8)

API Command POST Required? Description Developer Status Notes
CreateThumbnail Yes TBC Not started
GetImageInfo No TBC Not Started
GetImageInfoList No TBC Not started
GetSyncStatus No TBC. Not Started
RemoveImage Yes TBC. Not started
RenameImage Yes TBC. Not Started
StartSync Yes TBC. Not started
StopSync Yes TBC. Not Started

Music Service API List (2)

API Command POST Required? Description Developer Status Notes
GetTrack Yes Gets metadata for an individual music track Not started
GetTrackList No Gets metadata for all music tracks Not Started

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 Completed
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. bill6502 Not started
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 bill6502 Not started
GetSetting No Gets an individual setting in 0.28+ bill6502 Completed
GetSettingList No Gets a list of settings in 0.28+ bill6502 Not Started
GetStorageGroupDirs No Get one storage group's directory information bill6502 Not started
GetTimeZone No Get the current time zone information bill6502 Completed
ManageDigestUser (v30+) Yes Add/Remove/ChangePassword for API users bill6502 Not started May be removed
ManageUrlProtection (v30+) Yes Setup digest protection for none, one or more services bill6502 Not Started May be removed
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 Started
GetBluray No Query technical data for a Blu-ray disc or folder. Peter Bennett Started
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 Started
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 Started
RemoveVideoFromDB Yes Remove a single video from the database by database id. Peter Bennett Started
SetSavedBookmark Yes Save a bookmark for a video Peter Bennett Started
UpdateVideoMetadata Yes Updates the metadata of a video Peter Bennett Started
UpdateVideoWatchedStatus Yes Update the watched flag for a video Peter Bennett Started

Status Service API List

API Command POST Required? Description Developer Status Notes
Status No Get Backend Status in HTML Not started Predates Services API. Returns only HTML
GetStatusHTML No Get Backend Status in HTML Not Started Predates Services API. Returns only HTML
GetStatus No Get Backend Status in XML Not started Predates Services API. Returns only XML
xml No Get Backend Status in XML Not Started Predates Services API. Returns only XML