This is an old revision of the document!
HDHomeRun Device Discover API
This is a mirror of the documentation from: https://www.silicondust.com/hdhomerun/hdhomerun_discover_api.pdf
20240203-1
Low level C Library
https://download.silicondust.com/hdhomerun/libhdhomerun.tgz
https://github.com/Silicondust/libhdhomerun
The libhdhomerun library is available under a commercial license suitable for compiling directly into an app – contact Silicondust to request.
Requires C99 compliant compiler.
Example code
See hdhomerun_discover_example.c for an example of using the discover API. Header files:
Include hdhomerun.h to access libhdhomerun APIs.
The discover API is declared in hdhomerun_discover.h.
Source files required for discover
| File | Purpose |
|---|---|
| All platforms | |
| hdhomerun_discover.c | Discover API |
| hdhomerun_debug.c | Internal debug logging |
| hdhomerun_pkt.c | Internal packet handling |
| hdhomerun_sock.c | Internal socket handling (common code) |
| Linux / Android | |
| hdhomerun_os_posix.c | Internal OS wrapper functions |
| hdhomerun_sock_posix.c | Internal socket handling |
| hdhomerun_sock_netlink.c | Internal IP address detection |
| Mac / BSD | |
| hdhomerun_os_posix.c | Internal OS wrapper functions |
| hdhomerun_sock_posix.c | Internal socket handling |
| hdhomerun_sock_getifaddrs.c | Internal IP address detection |
| Windows | |
| hdhomerun_os_windows.c | Internal OS wrapper functions |
| hdhomerun_sock_windows.c | Internal IP address detection & socket handling |
hdhomerun_discover_create()
struct hdhomerun_discover_t *hdhomerun_discover_create(struct hdhomerun_debug_t *dbg);
Creates a discover object for managing / executing the discover process. The object may be maintained across the lifespan of the app or may be created and destroyed for each discover.
If the app polls discover often the discover object should be maintained and reused to avoid excessive cycling through local port numbers.
Parameters:
- dbg: debug object for debug logging or NULL if not using logging.
Returns:
- Discover object. Free using hdhomerun_discover_destroy().
hdhomerun_discover_destroy()
void hdhomerun_discover_destroy(struct hdhomerun_discover_t *ds);
Frees all resources associated with the given discover object.
Parameters:
- ds: discover object to free.
Returns:
- None.
hdhomerun_discover2_find_devices_broadcast()
int hdhomerun_discover2_find_devices_broadcast(struct hdhomerun_discover_t *ds, uint32_t flags, uint32_t const device_types[], size_t device_types_count);
Execute discover process to find devices of the specified type(s) on the local network(s). Results from any prior discover are wiped.
This is the primary API to discover devices.
Execution time is 400ms.
Parameters:
- ds: discover object.
- flags: specify which IP types to use for discover. Multiple flags can be specified by OR’ing together:
HDHOMERUN_DISCOVER_FLAGS_IPV4_GENERAL Discover using all local IPv4 addresses (excluding localhost). HDHOMERUN_DISCOVER_FLAGS_IPV4_LOCALHOST Discover via IPv4 localhost. Specify if the local system can support running the HDHomeRun record engine for storing recordings on the local system. HDHOMERUN_DISCOVER_FLAGS_IPV6_GENERAL Discover using all global and site-local IPv6 addresses. HDHOMERUN_DISCOVER_FLAGS_IPV6_LINKLOC Discover using all link-local IPv6 addresses. Only specify if the application supports tracking IPv6 scope IDs. HDHOMERUN_DISCOVER_FLAGS_IPV6_LOCALHOST Discover via IPv6 localhost. Specify if the local system can support running the HDHomeRun record engine for storing recordings on the local system.
- device_types: array of uint32_t values specifying the types of devices to detect. Values:
HDHOMERUN_DEVICE_TYPE_TUNE Detect HDHomeRun tuner devices. HDHOMERUN_DEVICE_TYPE_STORAGE Detect HDHomeRun record engines.
- device_types_count: number of entries in the device_types array provided.
Returns:
- 1 if one or more devices were found.
- 0 if the discover process completed without error but no devices were found.
- -1 if the discover process failed.
Notes:
Applications that support the complete HDHomeRun DVR system should pass in a 2 element device_type array indicating both TUNER and STORAGE.
Applications that support live TV or don’t use the HDHomeRun DVR system should pass in a 1 element device_type array indicating TUNER.
HDHomeRun tuner models with a hard drive present respond as both TUNER and STORAGE and report both TUNER and STORAGE types in the results.
hdhomerun_discover2_find_devices_targeted()
int hdhomerun_discover2_find_devices_targeted(struct hdhomerun_discover_t *ds, const struct sockaddr *target_addr, const uint32_t device_types[], size_t device_types_count);