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_TUNER
- 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.