code.vuplus.com Git - vuplus_xbmc/blob - lib/libhdhomerun/hdhomerun_device.h

   1 /*
   2  * hdhomerun_device.h
   3  *
   4  * Copyright © 2006-2008 Silicondust Engineering Ltd. <www.silicondust.com>.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 3 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * As a special exception to the GNU Lesser General Public License,
  20  * you may link, statically or dynamically, an application with a
  21  * publicly distributed version of the Library to produce an
  22  * executable file containing portions of the Library, and
  23  * distribute that executable file under terms of your choice,
  24  * without any of the additional requirements listed in clause 4 of
  25  * the GNU Lesser General Public License.
  26  *
  27  * By "a publicly distributed version of the Library", we mean
  28  * either the unmodified Library as distributed by Silicondust, or a
  29  * modified version of the Library that is distributed under the
  30  * conditions defined in the GNU Lesser General Public License.
  31  */
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 #define HDHOMERUN_DEVICE_MAX_TUNE_TO_LOCK_TIME 1500
  38 #define HDHOMERUN_DEVICE_MAX_LOCK_TO_DATA_TIME 2000
  39 #define HDHOMERUN_DEVICE_MAX_TUNE_TO_DATA_TIME (HDHOMERUN_DEVICE_MAX_TUNE_TO_LOCK_TIME + HDHOMERUN_DEVICE_MAX_LOCK_TO_DATA_TIME)
  40
  41 #define HDHOMERUN_STATUS_COLOR_NEUTRAL  0xFFFFFFFF
  42 #define HDHOMERUN_STATUS_COLOR_RED              0xFFFF0000
  43 #define HDHOMERUN_STATUS_COLOR_YELLOW   0xFFFFFF00
  44 #define HDHOMERUN_STATUS_COLOR_GREEN    0xFF00C000
  45
  46 #define HDHOMERUN_TARGET_PROTOCOL_UDP "udp"
  47 #define HDHOMERUN_TARGET_PROTOCOL_RTP "rtp"
  48
  49 /*
  50  * Create a device object.
  51  *
  52  * Typically a device object will be created for each tuner.
  53  * It is valid to have multiple device objects communicating with a single HDHomeRun.
  54  *
  55  * For example, a threaded application that streams video from 4 tuners (2 HDHomeRun devices) and has
  56  * GUI feedback to the user of the selected tuner might use 5 device objects: 4 for streaming video
  57  * (one per thread) and one for the GUI display that can just between tuners.
  58  *
  59  * This function will not attempt to connect to the device.
  60  * The connection will be established when first used.
  61  *
  62  * uint32_t device_id = 32-bit device id of device. Set to HDHOMERUN_DEVICE_ID_WILDCARD to match any device ID.
  63  * uint32_t device_ip = IP address of device. Set to 0 to auto-detect.
  64  * unsigned int tuner = tuner index (0 or 1). Can be changed later by calling hdhomerun_device_set_tuner.
  65  * struct hdhomerun_debug_t *dbg: Pointer to debug logging object. May be NULL.
  66  *
  67  * Returns a pointer to the newly created device object.
  68  *
  69  * When no longer needed, the socket should be destroyed by calling hdhomerun_device_destroy.
  70  *
  71  * The hdhomerun_device_create_from_str function creates a device object from the given device_str.
  72  * The device_str parameter can be any of the following forms:
  73  *     <device id>
  74  *     <device id>-<tuner index>
  75  *     <ip address>
  76  * If the tuner index is not included in the device_str then it is set to zero.
  77  * Use hdhomerun_device_set_tuner or hdhomerun_device_set_tuner_from_str to set the tuner.
  78  *
  79  * The hdhomerun_device_set_tuner_from_str function sets the tuner from the given tuner_str.
  80  * The tuner_str parameter can be any of the following forms:
  81  *     <tuner index>
  82  *     /tuner<tuner index>
  83  */
  84 extern LIBTYPE struct hdhomerun_device_t *hdhomerun_device_create(uint32_t device_id, uint32_t device_ip, unsigned int tuner, struct hdhomerun_debug_t *dbg);
  85 extern LIBTYPE struct hdhomerun_device_t *hdhomerun_device_create_from_str(const char *device_str, struct hdhomerun_debug_t *dbg);
  86 extern LIBTYPE void hdhomerun_device_destroy(struct hdhomerun_device_t *hd);
  87
  88 /*
  89  * Get the device id, ip, or tuner of the device instance.
  90  */
  91 extern LIBTYPE uint32_t hdhomerun_device_get_device_id(struct hdhomerun_device_t *hd);
  92 extern LIBTYPE uint32_t hdhomerun_device_get_device_ip(struct hdhomerun_device_t *hd);
  93 extern LIBTYPE uint32_t hdhomerun_device_get_device_id_requested(struct hdhomerun_device_t *hd);
  94 extern LIBTYPE uint32_t hdhomerun_device_get_device_ip_requested(struct hdhomerun_device_t *hd);
  95 extern LIBTYPE unsigned int hdhomerun_device_get_tuner(struct hdhomerun_device_t *hd);
  96
  97 extern LIBTYPE void hdhomerun_device_set_device(struct hdhomerun_device_t *hd, uint32_t device_id, uint32_t device_ip);
  98 extern LIBTYPE void hdhomerun_device_set_tuner(struct hdhomerun_device_t *hd, unsigned int tuner);
  99 extern LIBTYPE int hdhomerun_device_set_tuner_from_str(struct hdhomerun_device_t *hd, const char *tuner_str);
 100
 101 /*
 102  * Get the local machine IP address used when communicating with the device.
 103  *
 104  * This function is useful for determining the IP address to use with set target commands.
 105  *
 106  * Returns 32-bit IP address with native endianness, or 0 on error.
 107  */
 108 extern LIBTYPE uint32_t hdhomerun_device_get_local_machine_addr(struct hdhomerun_device_t *hd);
 109
 110 /*
 111  * Get operations.
 112  *
 113  * struct hdhomerun_tuner_status_t *status = Pointer to caller supplied status struct to be populated with result.
 114  * const char **p<name> = Caller supplied char * to be updated to point to the result string. The string will remain
 115  *              valid until another call to a device function.
 116  *
 117  * Returns 1 if the operation was successful.
 118  * Returns 0 if the operation was rejected.
 119  * Returns -1 if a communication error occurred.
 120  */
 121 extern LIBTYPE int hdhomerun_device_get_tuner_status(struct hdhomerun_device_t *hd, char **pstatus_str, struct hdhomerun_tuner_status_t *status);
 122 extern LIBTYPE int hdhomerun_device_get_tuner_streaminfo(struct hdhomerun_device_t *hd, char **pstreaminfo);
 123 extern LIBTYPE int hdhomerun_device_get_tuner_channel(struct hdhomerun_device_t *hd, char **pchannel);
 124 extern LIBTYPE int hdhomerun_device_get_tuner_channelmap(struct hdhomerun_device_t *hd, char **pchannelmap);
 125 extern LIBTYPE int hdhomerun_device_get_tuner_filter(struct hdhomerun_device_t *hd, char **pfilter);
 126 extern LIBTYPE int hdhomerun_device_get_tuner_program(struct hdhomerun_device_t *hd, char **pprogram);
 127 extern LIBTYPE int hdhomerun_device_get_tuner_target(struct hdhomerun_device_t *hd, char **ptarget);
 128 extern LIBTYPE int hdhomerun_device_get_tuner_plotsample(struct hdhomerun_device_t *hd, struct hdhomerun_plotsample_t **psamples, size_t *pcount);
 129 extern LIBTYPE int hdhomerun_device_get_tuner_lockkey_owner(struct hdhomerun_device_t *hd, char **powner);
 130 extern LIBTYPE int hdhomerun_device_get_ir_target(struct hdhomerun_device_t *hd, char **ptarget);
 131 extern LIBTYPE int hdhomerun_device_get_lineup_location(struct hdhomerun_device_t *hd, char **plocation);
 132 extern LIBTYPE int hdhomerun_device_get_version(struct hdhomerun_device_t *hd, char **pversion_str, uint32_t *pversion_num);
 133
 134 extern LIBTYPE uint32_t hdhomerun_device_get_tuner_status_ss_color(struct hdhomerun_tuner_status_t *status);
 135 extern LIBTYPE uint32_t hdhomerun_device_get_tuner_status_snq_color(struct hdhomerun_tuner_status_t *status);
 136 extern LIBTYPE uint32_t hdhomerun_device_get_tuner_status_seq_color(struct hdhomerun_tuner_status_t *status);
 137
 138 extern LIBTYPE const char *hdhomerun_device_get_model_str(struct hdhomerun_device_t *hd);
 139
 140 /*
 141  * Set operations.
 142  *
 143  * const char *<name> = String to send to device.
 144  *
 145  * Returns 1 if the operation was successful.
 146  * Returns 0 if the operation was rejected.
 147  * Returns -1 if a communication error occurred.
 148  */
 149 extern LIBTYPE int hdhomerun_device_set_tuner_channel(struct hdhomerun_device_t *hd, const char *channel);
 150 extern LIBTYPE int hdhomerun_device_set_tuner_channelmap(struct hdhomerun_device_t *hd, const char *channelmap);
 151 extern LIBTYPE int hdhomerun_device_set_tuner_filter(struct hdhomerun_device_t *hd, const char *filter);
 152 extern LIBTYPE int hdhomerun_device_set_tuner_filter_by_array(struct hdhomerun_device_t *hd, unsigned char filter_array[0x2000]);
 153 extern LIBTYPE int hdhomerun_device_set_tuner_program(struct hdhomerun_device_t *hd, const char *program);
 154 extern LIBTYPE int hdhomerun_device_set_tuner_target(struct hdhomerun_device_t *hd, char *target);
 155 extern LIBTYPE int hdhomerun_device_set_tuner_target_to_local_protocol(struct hdhomerun_device_t *hd, const char *protocol);
 156 extern LIBTYPE int hdhomerun_device_set_tuner_target_to_local(struct hdhomerun_device_t *hd);
 157 extern LIBTYPE int hdhomerun_device_set_ir_target(struct hdhomerun_device_t *hd, const char *target);
 158 extern LIBTYPE int hdhomerun_device_set_lineup_location(struct hdhomerun_device_t *hd, const char *location);
 159
 160 /*
 161  * Get/set a named control variable on the device.
 162  *
 163  * const char *name: The name of var to get/set (c-string). The supported vars is device/firmware dependant.
 164  * const char *value: The value to set (c-string). The format is device/firmware dependant.
 165
 166  * char **pvalue: If provided, the caller-supplied char pointer will be populated with a pointer to the value
 167  *              string returned by the device, or NULL if the device returned an error string. The string will remain
 168  *              valid until the next call to a control sock function.
 169  * char **perror: If provided, the caller-supplied char pointer will be populated with a pointer to the error
 170  *              string returned by the device, or NULL if the device returned an value string. The string will remain
 171  *              valid until the next call to a control sock function.
 172  *
 173  * Returns 1 if the operation was successful (pvalue set, perror NULL).
 174  * Returns 0 if the operation was rejected (pvalue NULL, perror set).
 175  * Returns -1 if a communication error occurs.
 176  */
 177 extern LIBTYPE int hdhomerun_device_get_var(struct hdhomerun_device_t *hd, const char *name, char **pvalue, char **perror);
 178 extern LIBTYPE int hdhomerun_device_set_var(struct hdhomerun_device_t *hd, const char *name, const char *value, char **pvalue, char **perror);
 179
 180 /*
 181  * Tuner locking.
 182  *
 183  * The hdhomerun_device_tuner_lockkey_request function is used to obtain a lock
 184  * or to verify that the hdhomerun_device object still holds the lock.
 185  * Returns 1 if the lock request was successful and the lock was obtained.
 186  * Returns 0 if the lock request was rejected.
 187  * Returns -1 if a communication error occurs.
 188  *
 189  * The hdhomerun_device_tuner_lockkey_release function is used to release a
 190  * previously held lock. If locking is used then this function must be called
 191  * before destroying the hdhomerun_device object.
 192  */
 193 extern LIBTYPE int hdhomerun_device_tuner_lockkey_request(struct hdhomerun_device_t *hd, char **perror);
 194 extern LIBTYPE int hdhomerun_device_tuner_lockkey_release(struct hdhomerun_device_t *hd);
 195 extern LIBTYPE int hdhomerun_device_tuner_lockkey_force(struct hdhomerun_device_t *hd);
 196
 197 /*
 198  * Intended only for non persistent connections; eg, hdhomerun_config.
 199  */
 200 extern LIBTYPE void hdhomerun_device_tuner_lockkey_use_value(struct hdhomerun_device_t *hd, uint32_t lockkey);
 201
 202 /*
 203  * Wait for tuner lock after channel change.
 204  *
 205  * The hdhomerun_device_wait_for_lock function is used to detect/wait for a lock vs no lock indication
 206  * after a channel change.
 207  *
 208  * It will return quickly if a lock is aquired.
 209  * It will return quickly if there is no signal detected.
 210  * Worst case it will time out after 1.5 seconds - the case where there is signal but no lock.
 211  */
 212 extern LIBTYPE int hdhomerun_device_wait_for_lock(struct hdhomerun_device_t *hd, struct hdhomerun_tuner_status_t *status);
 213
 214 /*
 215  * Stream a filtered program or the unfiltered stream.
 216  *
 217  * The hdhomerun_device_stream_start function initializes the process and tells the device to start streamin data.
 218  *
 219  * uint16_t program_number = The program number to filer, or 0 for unfiltered.
 220  *
 221  * Returns 1 if the oprtation started successfully.
 222  * Returns 0 if the operation was rejected.
 223  * Returns -1 if a communication error occurs.
 224  *
 225  * The hdhomerun_device_stream_recv function should be called periodically to receive the stream data.
 226  * The buffer can losslessly store 1 second of data, however a more typical call rate would be every 64ms.
 227  *
 228  * The hdhomerun_device_stream_stop function tells the device to stop streaming data.
 229  */
 230 extern LIBTYPE int hdhomerun_device_stream_start(struct hdhomerun_device_t *hd);
 231 extern LIBTYPE int hdhomerun_device_stream_refresh_target(struct hdhomerun_device_t *hd);
 232 extern LIBTYPE uint8_t *hdhomerun_device_stream_recv(struct hdhomerun_device_t *hd, size_t max_size, size_t *pactual_size);
 233 extern LIBTYPE void hdhomerun_device_stream_flush(struct hdhomerun_device_t *hd);
 234 extern LIBTYPE void hdhomerun_device_stream_stop(struct hdhomerun_device_t *hd);
 235
 236 /*
 237  * Channel scan API.
 238  */
 239 extern LIBTYPE int hdhomerun_device_channelscan_init(struct hdhomerun_device_t *hd, const char *channelmap);
 240 extern LIBTYPE int hdhomerun_device_channelscan_advance(struct hdhomerun_device_t *hd, struct hdhomerun_channelscan_result_t *result);
 241 extern LIBTYPE int hdhomerun_device_channelscan_detect(struct hdhomerun_device_t *hd, struct hdhomerun_channelscan_result_t *result);
 242 extern LIBTYPE uint8_t hdhomerun_device_channelscan_get_progress(struct hdhomerun_device_t *hd);
 243
 244 /*
 245  * Check that the device is running the recommended firmware.
 246  *
 247  * uint32_t features: Reserved for future use. Set to zero.
 248  *
 249  * Returns 1 if the firmware meets the minimum requriements for all operations.
 250  * Returns 0 if th firmware does not meet the minimum requriements for all operations.
 251  * Returns -1 if an error occurs.
 252  */
 253 extern LIBTYPE int hdhomerun_device_firmware_version_check(struct hdhomerun_device_t *hd, uint32_t features);
 254
 255 /*
 256  * Upload new firmware to the device.
 257  *
 258  * FILE *upgrade_file: File pointer to read from. The file must have been opened in binary mode for reading.
 259  *
 260  * Returns 1 if the upload succeeded.
 261  * Returns 0 if the upload was rejected.
 262  * Returns -1 if an error occurs.
 263  */
 264 extern LIBTYPE int hdhomerun_device_upgrade(struct hdhomerun_device_t *hd, FILE *upgrade_file);
 265
 266 /*
 267  * Low level accessor functions.
 268  */
 269 extern LIBTYPE struct hdhomerun_control_sock_t *hdhomerun_device_get_control_sock(struct hdhomerun_device_t *hd);
 270 extern LIBTYPE struct hdhomerun_video_sock_t *hdhomerun_device_get_video_sock(struct hdhomerun_device_t *hd);
 271
 272 /*
 273  * Debug print internal stats.
 274  */
 275 extern LIBTYPE void hdhomerun_device_debug_print_video_stats(struct hdhomerun_device_t *hd);
 276 extern LIBTYPE void hdhomerun_device_get_video_stats(struct hdhomerun_device_t *hd, struct hdhomerun_video_stats_t *stats);
 277
 278 #ifdef __cplusplus
 279 }
 280 #endif