Difference between revisions of "Services API V2 Conversion"
(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
Contents
- 1 Services API V2 Conversion
- 2 Capture Service API List (8)
- 3 Channel Service API List (15)
- 4 Content Service API List (22)
- 5 Dvr Service API List (51)
- 6 Frontend Service API List
- 7 Guide Service API List (9)
- 8 Image Service API List (8)
- 9 Music Service API List (2)
- 10 Myth Service API List (32)
- 11 Video Service API List (12)
- 12 Status Service API List
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 |