Differences

This shows you the differences between two versions of the page.

--- discovery_api [2024/02/07 02:38]
neds
+++ discovery_api [2024/02/07 19:05] (current)
neds [Low level C Library]
@@ Line 17: / Line 17: @@
 **Example code:**
-See hdhomerun_discover_example.c for an example of using the discover API.
+See [[https://github.com/Silicondust/libhdhomerun/blob/master/hdhomerun_discover_example.c|hdhomerun_discover_example.c]] for an example of using the discover API.
 Header files:
@@ Line 133: / Line 133: @@
     * IPv6 link-local – the Scope ID is used if specified, auto-detected if 0.
     * IPv6 non link-local – set Scope ID to 0.
-  * **device_types:** array of uint32_t values specifying the types of devices to detect. See hdhomerun_discover2_find_devices_broadcast() for the description.
+  * **device_types:** array of uint32_t values specifying the types of devices to detect. See [[#hdhomerun_discover2_find_devices_broadcast()]] for the description.
   * **device_types_count:** number of entries in the device_types array provided.
@@ Line 154: / Line 154: @@
 **Parameters:**
   * **ds:** discover object.
-  * **flags:** specify which IP types to use for discover. See hdhomerun_discover2_find_devices_broadcast() for the description.
+  * **flags:** specify which IP types to use for discover. See [[#hdhomerun_discover2_find_devices_broadcast()]] for the description.
   * **device_id:** uint32_t device id (serial number) of the device to locate.
@@ Line 176: / Line 176: @@
 **Parameters:**
   * **ds:** discover object.
-  * **flags:** specify which IP types to use for discover. See hdhomerun_discover2_find_devices_broadcast() for the description.
+  * **flags:** specify which IP types to use for discover. See [[#hdhomerun_discover2_find_devices_broadcast()]] for the description.
   * **target_addr:** IP address to send discover request to.
     * IPv4 and IPv6 addresses supported.
@@ Line 213: / Line 213: @@
 <WRAP indent>
 **Parameters:**
-  * device: device object from hdhomerun_discover2_iter_device_first() or previous call to hdhomerun_discover2_iter_device_next().
+  * **device:** device object from hdhomerun_discover2_iter_device_first() or previous call to hdhomerun_discover2_iter_device_next().
 **Returns:**
   * Device object. Resource maintained by the ds discover object – do not store or free.
@@ Line 250: / Line 250: @@
 **Returns:**
   * True if the device is of the type specified by the device_type parameter.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_get_device_id() =====
+<WRAP indent>
+<code>uint32_t hdhomerun_discover2_device_get_device_id(struct hdhomerun_discover2_device_t *device);</code>
+Return the 32-bit Device ID (serial number) of the device if the device is HDHomeRun hardware.
+Devices of type TUNER are hardware products and always have a Device ID.
+Devices of type STORAGE may be a hardware product with a Device ID or may be a software product with no Device ID (such as the HDHomeRun DVR record engine installed on a PC or NAS). To uniquely identify devices of type STORAGE use the alternative hdhomerun_discover2_device_get_storage_id() API.
+<WRAP indent>
+**Parameters:**
+  * **device:** device object from hdhomerun_discover2_iter_device_first() or hdhomerun_discover2_iter_device_next().
+**Returns:**
+  * 32-bit Device ID (serial number) of the HDHomeRun hardware.
+  * 0 if the device does not have a Device ID, for example a DVR record engine installed on a PC or NAS.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_get_storage_id() =====
+<WRAP indent>
+<code>const char *hdhomerun_discover2_device_get_device_auth(struct hdhomerun_discover2_device_t *device);</code>
+Return the UUID string Storage ID of the device.
+<WRAP indent>
+**Parameters:**
+  * **device:** device object from hdhomerun_discover2_iter_device_first() or hdhomerun_discover2_iter_device_next().
+**Returns:**
+  * UUID string Storage ID. The returned result must be copied if the value needs to be accessed by the app beyond the scope of the current discover action.
+  * NULL if the device does not have a Storage ID, for example a tuner without storage capabilities.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_get_tuner_count() =====
+<WRAP indent>
+<code>uint8_t hdhomerun_discover2_device_get_tuner_count(struct hdhomerun_discover2_device_t *device);</code>
+Return the number of tuners the device has.
+<WRAP indent>
+**Parameters:**
+  * **device:** device object from hdhomerun_discover2_iter_device_first() or hdhomerun_discover2_iter_device_next().
+**Returns:**
+  * The number of tuners the device has.
+  * 0 if the device does not have tuners.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_get_device_auth() =====
+<WRAP indent>
+<code>const char *hdhomerun_discover2_device_get_device_auth(struct hdhomerun_discover2_device_t *device);</code>
+The DeviceAuth string reported by the device. Used to access HDHomeRun cloud APIs.
+<WRAP indent>
+**Parameters:**
+  * **device:** device object from hdhomerun_discover2_iter_device_first() or hdhomerun_discover2_iter_device_next().
+**Returns:**
+  * The DeviceAuth string reported by the device. The returned result must be copied if the value needs to be accessed by the app beyond the scope of the current discover action.
+  * NULL if the device did not report a DeviceAuth string during discovery.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_iter_device_if_first() =====
+<WRAP indent>
+<code>struct hdhomerun_discover2_device_if_t *hdhomerun_discover2_iter_device_if_first(struct hdhomerun_discover2_device_t *device);</code>
+A device can have multiple IP addresses, for example IPv4, IPv6 global, and IPv6 link-local. Use hdhomerun_discover2_iter_device_if_first() to obtain the first device-if object (IP address object) in the list associated with a device. This object is used to query the IP address and associated URLs.
+A typical application only needs to get the first device-if object and does not need to iterate through the list of device-if objects.
+<WRAP indent>
+**Parameters:**
+  * **device:** device object from hdhomerun_discover2_iter_device_first() or hdhomerun_discover2_iter_device_next().
+**Returns:**
+  * Device-IF object. Resource maintained by the ds discover object – do not store or free. A device-if object is always present and cannot be NULL.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_iter_device_if_next() =====
+<WRAP indent>
+<code>struct hdhomerun_discover2_device_if_t *hdhomerun_discover2_iter_device_if_next(struct hdhomerun_discover2_device_if_t *device_if)</code>
+Return the next device-if object (IP address object) in the list associated with a device. This object is used to query the IP address and associated URLs.
+A typical application only needs to get the first device-if object and does not need to iterate through the list of device-if objects.
+<WRAP indent>
+**Parameters:**
+  * **device_if:** device-if object from hdhomerun_discover2_iter_device_if_first() or previous call to hdhomerun_discover2_iter_device_if_next().
+**Returns:**
+  * Device-IF object. Resource maintained by the ds discover object – do not store or free.
+  * NULL when the end of the list has been reached.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_if_get_ip_addr() =====
+<WRAP indent>
+<code>void hdhomerun_discover2_device_if_get_ip_addr(struct hdhomerun_discover2_device_if_t *device_if, struct sockaddr_storage *ip_addr);</code>
+Return the IP address of the device.
+<WRAP indent>
+**Parameters:**
+  * **device_if:** device-if object from hdhomerun_discover2_iter_device_if_first() or hdhomerun_discover2_iter_device_if_next().
+  * **ip_addr:** sockaddr_storage struct where the IP address is returned.
+**Returns:**
+  * None.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_if_get_base_url() =====
+<WRAP indent>
+<code>const char *hdhomerun_discover2_device_if_get_base_url(struct hdhomerun_discover2_device_if_t *device_if);</code>
+Return the base URL of the device as a string.
+<WRAP indent>
+**Parameters:**
+  * **device_if:** device-if object from hdhomerun_discover2_iter_device_if_first() or hdhomerun_discover2_iter_device_if_next().
+**Returns:**
+  * Base URL as a string. The returned result must be copied if the value needs to be accessed by the app beyond the scope of the current discover action. The Base URL is always present and cannot be NULL.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_if_get_lineup_url() =====
+<WRAP indent>
+<code>const char *hdhomerun_discover2_device_if_get_lineup_url(struct hdhomerun_discover2_device_if_t *device_if);</code>
+Return the lineup URL (lineup.json) of the device as a string. Only present for devices of type TUNER.
+<WRAP indent>
+**Parameters:**
+  * **device_if:** device-if object from hdhomerun_discover2_iter_device_if_first() or hdhomerun_discover2_iter_device_if_next().
+**Returns:**
+  * Lineup URL as a string. The returned result must be copied if the value needs to be accessed by the app beyond the scope of the current discover action.
+  * NULL if the device is not type TUNER.
+</WRAP>
+</WRAP>
+===== hdhomerun_discover2_device_if_get_storage_url() =====
+<WRAP indent>
+<code>const char *hdhomerun_discover2_device_if_get_storage_url(struct hdhomerun_discover2_device_if_t *device_if);</code>
+Return the storage URL (recorded_files.json) of the device as a string. Only present for devices of type STORAGE.
+<WRAP indent>
+**Parameters:**
+  * **device_if:** device-if object from hdhomerun_discover2_iter_device_if_first() or hdhomerun_discover2_iter_device_if_next().
+**Returns:**
+  * Storage URL as a string. The returned result must be copied if the value needs to be accessed by the app beyond the scope of the current discover action.
+  * NULL if the device is not type STORAGE.
 </WRAP>

development