org.jmythapi.protocol.response
Interface IMythResponse<E extends Enum<E>>

Type Parameters:

E - the type of the response object properties

All Superinterfaces:

Cloneable, IPropertyAware<E>, ISendable, IVersionable

All Known Implementing Classes:

AFreeSpace, AMythEvent, AMythResponse, AProgramInfo, ARecorderProgramInfo, ARecordings, AskRecording, ClearSettingsCache, ClientErrorEvent, CommflagStart, DoneRecording, DownloadFileFinished, DownloadFileUpdate, FileStatus, FileTransfer, FreeInputsList, FreeSpace, FreeSpaceList, FreeSpaceList.Entry, FreeSpaceSummary, GuideDataThrough, InputInfoFree, InputInfoTuned, LiveTvChainUpdate, Load, MemStats, Pixmap, PixmapGenerated, ProgramInfo, ProgramInfoList, RecorderChannelInfo, RecorderChannelPrefixStatus, RecorderInfo, RecorderNextProgramInfo, RecorderProgramInfo, RecordingListChangeAdd, RecordingListChangeAny, RecordingListChangeDelete, RecordingListChangeUpdate, RecordingsConflicting, RecordingsExpiring, RecordingsPending, RecordingsScheduled, RecordingStatus, RemoteEncoderBusyStatus, RemoteEncoderState, ResetIdleTime, RingBuffer, ScheduleChange, Setting, ShutdownCountdown, StorageGroupFile, StorageGroupFileList, SystemEvent, Timezone, TunerInfo, UpdateFileSize, UpdateProgInfo, Uptime, VideoList, VideoListChange, VideoListNoChange

public interface IMythResponse<E extends Enum<E>>
extends IPropertyAware<E>, IVersionable, ISendable

This interface represents a MythTV response object.

A response object consists of a list of response arguments. This response arguments are simple strings that were received over network in the form of a packet.

Using Response Objects:

To use a response object, a previously received response packet needs to be converted into a more easily to read response-object, via the utility class ResponseUtils:

    // read the response packet from network
    IMythPacket resp = connection.readPacket();
    
    // convert the response packet into a specific response object
    IRecorderInfo recorderInfo = ResponseUtils.readFrom(RecorderInfo.class, resp);
 

Response Object Properties:

All response objects are property-aware. Therefore the advantage of a response-object in comparison to a the raw packet is the enumeration property class, that belongs to each type of response object.

Property Position and Version Range

The enumeration properties of a response-object are used to describe, at which position in the response-arguments list, the value for a specific property can be found. Additionally for each property a version-range is specified, describing in which protocol version a specific property is part of a response.

Usage example:

For example if we have received the arguments of a recorder-info object over network, we can convert the received packet to a IRecorderInfo object (as show in the following example) and then we can use the enumeration property HOSTNAME to get the hostname of the recorder.

    IMythPacket resp = ...; // a previously received myth packet
 
    // convert the response packet into a specific response object
    RecorderInfo recorderInfo = ResponseUtils.readFrom(RecorderInfo.class, resp);
    
    // read a property value
   String hostName = recorderInfo.getPropertyValue(IRecorderInfo.Props.HOSTNAME);
   
   // the above call is similar to
   hostName = recorderInfo.getHostName();
 

The following protocol packets are send and received via network:

29	GET_NEXT_FREE_RECORDER[]:[]-1
26	1[]:[]192.168.0.2[]:[]6543

As shown above, the various arguments of response object can be fetched using the enumeration constants of the response object.
The advantage of this solution is, that you do not need to know, that the response argument hostname is located at position 1 in the response array. Furthermore the position of an argument may change depending of the protocol-version, the backend is speaking. When using the enumeration constants to fetch an argument, we do not need to take care about this. Moreover, an enumeration property may not be part of the response in the current protocol version. In this case the the property-aware object will just return null as value.

Which properties are valid for a given Protocol Version

The method IPropertyAware.getPropertyValue(Enum) internally uses helper function of the utility class EnumUtils to determine, which enumeration properties are available in which protocol-version and at which position in the response arguments array, the value for a given property can be found.

Usage example:

To iterate over all available properties of a response object the following can be done:

    EnumMap<IRecorderInfo.Props,String> props = recorderInfo.getPropertyMap();
    for(Entry<IRecorderInfo.Props,String> prop : props.entrySet()) {
       System.out.println(String.format(
          "Property %s=%s", prop.getKey(),prop.getValue()
       ));
    }
 

There are more useful functions to get and set properties. See IPropertyAware for details.

See Also:

ResponseUtils.readFrom(java.lang.Class, org.jmythapi.protocol.IMythPacket), EnumUtils

Method Summary

Methods inherited from interface org.jmythapi.IPropertyAware

getProperties, getProperty, getPropertyClass, getPropertyCount, getPropertyIndex, getPropertyMap, getPropertyValue, getPropertyValue, getPropertyValueObject, getPropertyValues, setPropertyValue, setPropertyValue, setPropertyValueObject

Methods inherited from interface org.jmythapi.IVersionable

getVersionNr

Methods inherited from interface org.jmythapi.protocol.ISendable

getPacket