|
Blurrr Network Service Discovery
1.0.0
|
#include <stdint.h>#include <stdbool.h>#include <stddef.h>Go to the source code of this file.
Typedefs | |
| typedef struct BNSD_Registration | BNSD_Registration |
| typedef struct BNSD_Discovery | BNSD_Discovery |
| typedef struct BNSD_Resolve | BNSD_Resolve |
| typedef void(* | BNSD_RegisterCallback) (struct BNSD_Registration *zeroconf_registration, const char *service_name, const char *service_type, const char *domain, int32_t blurrr_error_code, uint32_t flags, void *user_data) |
| Callback for BNSD_RegisterService. More... | |
| typedef void(* | BNSD_DiscoveryCallback) (struct BNSD_Discovery *zeroconf_discovery, const char *service_name, const char *service_type, const char *domain, bool is_added, int32_t blurrr_error_code, uint32_t flags, int32_t interface_index, void *user_data) |
| Callback for BNSD_StartDiscovery. More... | |
| typedef void(* | BNSD_ResolveCallback) (struct BNSD_Resolve *zeroconf_resolve, const char *service_name, const char *service_type, const char *domain, const char *full_name, const char *host_target, uint16_t port, const char *txt_record, uint16_t txt_record_length, int32_t blurrr_error_code, uint32_t flags, int32_t interface_index, void *user_data) |
| Callback for BNSD_StartResolve. More... | |
Functions | |
| bool | BNSD_IsSupported (void) |
| A quick test to see if the current system supports Zeroconf. More... | |
| bool | BNSD_Init (void *platform_init_object) |
| Initializes the library. More... | |
| void | BNSD_Quit (void) |
| Uninitializes the library. More... | |
| const char * | BNSD_GetBackendDescription (void) |
| Returns a string with the name of the backend in use. More... | |
| char * | BNSD_CreateDeviceNameString (void) |
| Returns a string with something that can be used as your computer name. More... | |
| void | BNSD_FreeString (char *str) |
| Frees the string created by BNSD_CreateDeviceNameString. More... | |
| size_t | BNSD_GetDeviceNameString (char *string_array, size_t array_length) |
| Returns a string with something that can be used as your computer name. More... | |
| struct BNSD_Registration * | BNSD_RegisterService (const char *service_name, const char *service_type, const char *domain, const char *host_name, uint16_t port, uint32_t flags, const char *txt_record, uint16_t txt_record_length, BNSD_RegisterCallback callback_function, void *user_data) |
| Starts advertising a new service. More... | |
| void | BNSD_UnregisterService (struct BNSD_Registration *registration_service) |
| Stops advertising an existing service and frees the resources. More... | |
| struct BNSD_Discovery * | BNSD_StartDiscovery (const char *service_type, const char *domain, uint32_t flags, BNSD_DiscoveryCallback callback_function, void *user_data) |
| Starts discovering all services that are currently advertised matching your critera. More... | |
| void | BNSD_StopDiscovery (struct BNSD_Discovery *discovery_service) |
| Stops discovering services for the specific instance. More... | |
| struct BNSD_Resolve * | BNSD_StartResolve (const char *service_name, const char *service_type, const char *domain, uint32_t flags, uint32_t time_out, BNSD_ResolveCallback callback_function, void *user_data) |
| Starts resolving the service you request. More... | |
| void | BNSD_StopResolve (struct BNSD_Resolve *resolve_service) |
| Stops resolving services for the specific instance. More... | |
| typedef struct BNSD_Registration BNSD_Registration |
| typedef struct BNSD_Discovery BNSD_Discovery |
| typedef struct BNSD_Resolve BNSD_Resolve |
| typedef void(* BNSD_RegisterCallback) (struct BNSD_Registration *zeroconf_registration, const char *service_name, const char *service_type, const char *domain, int32_t blurrr_error_code, uint32_t flags, void *user_data) |
Callback for BNSD_RegisterService.
Callback for BNSD_RegisterService. This shows you the final values for the service you registered if successfully registered, or an error code if something failed.
| zeroconf_registration | The pointer to the BNSD_Registration you got from BNSD_RegisterService. |
| service_name | The service name (e.g. "My Service") for the service you registered. Note: This name may be different than the name you requested with BNSD_RegisterService if it is determined that the name you requested is already in use. |
| service_type | The service type (e.g. "_daap._tcp."). |
| domain | The domain (e.g. "local."). |
| blurrr_error_code | 0 (BNSD_ERR_OK) if there was no error, otherwise one of the BNSD_ERR_* values. Note: If there was an error, some of the other parameters passed back by this function may be NULL. |
| flags | Reserved for future use (i.e. You can ignore this value): An integer bitmask to denote certain properties. BNSD_FLAGSCB_* will contain the different mask values. |
| user_data | The user_data pointer you passed to BNSD_RegisterService. |
| typedef void(* BNSD_DiscoveryCallback) (struct BNSD_Discovery *zeroconf_discovery, const char *service_name, const char *service_type, const char *domain, bool is_added, int32_t blurrr_error_code, uint32_t flags, int32_t interface_index, void *user_data) |
Callback for BNSD_StartDiscovery.
This will callback for every service discovered that meets your criteria when you called BNSD_StartDiscovery. Callbacks will continue to happen as services come and go until you call BNSD_StopDiscovery.
| zeroconf_discovery | The pointer to the BNSD_Discovery you got from BNSD_StartDiscovery. |
| service_name | The service name (e.g. "My Service"). |
| service_type | The service type (e.g. "_daap._tcp."). |
| domain | The domain (e.g. "local."). |
| is_added | If true, it means the service is currently advertised. If false, it means the service has gone away. |
| blurrr_error_code | 0 (BNSD_ERR_OK) if there was no error, otherwise one of the BNSD_ERR_* values. Note: If there was an error, some of the other parameters passed back by this function may be NULL. |
| flags | Reserved for future use (i.e. You can ignore this value): An integer bitmask to denote certain properties. BNSD_FLAGSCB_* will contain the different mask values. |
| interface_index | For Apple Bonjour and Avahi, this will give you the interface index this callback is associated with. On other platforms, this value will always be 0. This value is provided for informational purposes to help bookkeeping (see note about multiple callbacks). Otherwise, you can generally ignore this value. |
| user_data | The user_data pointer you passed to BNSD_StartDiscovery. |
| typedef void(* BNSD_ResolveCallback) (struct BNSD_Resolve *zeroconf_resolve, const char *service_name, const char *service_type, const char *domain, const char *full_name, const char *host_target, uint16_t port, const char *txt_record, uint16_t txt_record_length, int32_t blurrr_error_code, uint32_t flags, int32_t interface_index, void *user_data) |
Callback for BNSD_StartResolve.
This will callback for every service discovered that meets your criteria when you called BNSD_StartResolve. Callbacks will continue to happen as the service updates until you call BNSD_StopResolve or your requested time_out occurs. When a time_out callback occurs, many of the other fields will be NULL. After the time_out callback, future callbacks will be suppressed for convenience, but network resources are still alive and network traffic will continue, thus you should call BNSD_StopResolve(). Additionally, if you get back all the information you want before your time_out callback, consider calling BNSD_StopResolve immediately to free resources.
| zeroconf_resolve | The pointer to the BNSD_Resolve you got from BNSD_StartResolve. |
| service_name | The service name (e.g. "My Service"). |
| service_type | The service type (e.g. "_daap._tcp."). |
| domain | The domain (e.g. "local."). |
| full_name | This is the full name of the service, including escaping needed for DNS names (e.g. Not\032a\032real\032page._http_.tcp.local.) |
| host_target | The reachable host name of the machine the service resides on, (e.g. MacBook.local.). Names are preferred because they can stand in front of both IPv4 and IPv6 addresses, but if a name cannot be found, this could also be an IP address (e.g. 192.168.0.42 or an IPv6 address). (Android seems to have a bug where the IPv4 address is given even if there is an actual name (or IPv6 address also available) https://issuetracker.google.com/issues/80368263). |
| port | The port number in host byte order that the service is running on (e.g. MySsh._ssh._tcp.local. is running on port 22). |
| blurrr_error_code | 0 (BNSD_ERR_OK) if there was no error, BNSD_ERR_RESOLVE_TIMEOUT (1) if the time out BNSD_E otherwise one of the BNSD_ERR_* values. Note: If there was an error, some of the other parameters passed back by this function may be NULL. Tip: Notice that BNSD_ERR_OK and BNSD_ERR_RESOLVE_TIMEOUT are not-negative and real errors are negative. |
| txt_record | If the service has a TXT Record, this is the pointer to the array of bytes. Otherwise, this is NULL. Note: This is not a proper C string. It is not NULL terminated. This is in DNS TXT Record format, where each field entry starts with the number of bytes (an actual number, not a string) followed by that number characters, then repeat. (e.g. char txt_record[] = "\xfMyKey1=MyValue1\xfMyKey2=MyValue2"; where "\xf" is hex for 15). |
| txt_record_length | The length in bytes of the txt_record. Make sure to use this and don't use strlen() because the txt_record is not a proper C string. |
| flags | Reserved for future use: An integer bitmask to denote certain properties. BNSD_FLAGSCB_* will contain the different mask values. |
| interface_index | For Apple Bonjour and Avahi, this will give you the interface index this callback is associated with. On other platforms, this value will always be 0. This value is provided for informational purposes to help bookkeeping (see note about multiple callbacks). Otherwise, you can generally ignore this value. |
| user_data | The user_data pointer you passed to BNSD_Resolve. |
| anonymous enum |
Error code constants.
| anonymous enum |
| anonymous enum |
| bool BNSD_IsSupported | ( | void | ) |
A quick test to see if the current system supports Zeroconf.
On Android, it will check OS version for 4.1+. On Apple platforms, this will always return true. On Linux platforms, this will return true. (Currently expected to link to avahi, so launch time will fail without it.) On Windows, this first checks if Apple Bonjour for Windows is installed (looks for system-wide dnssd.dll), then if not found, checks for the Windows 10+ built in DNSSD UWP. This does not check for availability, i.e. the user has stopped the service. Specific allback results are needed to handle those failure cases.
| bool BNSD_Init | ( | void * | platform_init_object | ) |
Initializes the library.
On Apple, Linux, & Android, this is expected to return true. On Windows, this first tries to load Apple Bonjour for Windows if it is installed (looks for system-wide dnssd.dll), then if not found, tries to load the Windows 10+ built in DNSSD UWP.
| platform_init_object | On Android, you must pass a JNI jobject that is a Context. Use BlurrrPlatformAndroid_GetApplicationContext() or SDL_AndroidGetActivity() to get this object. For other platforms, pass NULL. |
| void BNSD_Quit | ( | void | ) |
Uninitializes the library.
| const char* BNSD_GetBackendDescription | ( | void | ) |
Returns a string with the name of the backend in use.
This is mostly used for diagnostic purposes, particularly for Windows where different backends could be running on diffent systems. Valid strings are: "Apple Bonjour" "Avahi" "Android Network Service Discovery" "Microsoft Windows DNS-SD UWP" "uninitialized"
| char* BNSD_CreateDeviceNameString | ( | void | ) |
Returns a string with something that can be used as your computer name.
| void BNSD_FreeString | ( | char * | str | ) |
Frees the string created by BNSD_CreateDeviceNameString.
| size_t BNSD_GetDeviceNameString | ( | char * | string_array, |
| size_t | array_length | ||
| ) |
Returns a string with something that can be used as your computer name.
| string_array | The buffer the result will be written into. Maybe NULL if you just want the return length. |
| array_length | The length of the string_array buffer. |
| struct BNSD_Registration* BNSD_RegisterService | ( | const char * | service_name, |
| const char * | service_type, | ||
| const char * | domain, | ||
| const char * | host_name, | ||
| uint16_t | port, | ||
| uint32_t | flags, | ||
| const char * | txt_record, | ||
| uint16_t | txt_record_length, | ||
| BNSD_RegisterCallback | callback_function, | ||
| void * | user_data | ||
| ) |
Starts advertising a new service.
This will register a new service and advertising it over the network.
| service_name | The name for the new service. Must be a string shorter than 63 characters and valid UTF-8. Example: "My Game Service on Mario's iPad". Passing NULL will cause a name to be generated for you. |
| service_type | The service type followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The service type must be an underscore, followed by 1-15 characters, which may be letters, digits, or hyphens. The transport protocol must be "_tcp" or "_udp". New service types should be registered at http://www.dns-sd.org/ServiceTypes.html. Trailing dots are allowed (e.g. "_ftp._tcp.") This does not support subtypes. May not be NULL. |
| domain | You should pass NULL which will utilize defaults. Advanced use cases of specifying a domain other than "local" may not be cross-platform. Trailing dots are allowed. |
| host_name | The host this service is residing on. It is recommended you pass NULL here, which defaults to your current device. Advanced use cases of this parameter are for proxying services (i.e. advertising a service on behalf of another device, e.g. advertise the service is coming from another machine, "macbook.local", instead of my current device.). Not all implementations are guaranteed to support this advanced use case. |
| port | The port, in host byte order, on which the service accepts connections. |
| flags | Reserved for future use. Pass 0 for now. |
| txt_record | Use this to provide a DNS TXT Record with your service. This may be NULL if you don't want one. This is in DNS TXT Record format, where each field entry starts with the number of bytes (an actual number, not a string) followed by that number characters, then repeat. (e.g. char txt_record[] = "\xfMyKey1=MyValue1\xfMyKey2=MyValue2"; where "\xf" is hex for 15). |
| txt_record_length | The length in bytes of the entire txt_record you supplied. Use 0 if you passed NULL. |
| callback_function | The callback function that will be invoked when your service is successfully created (or failed). Be aware that if you pick a service name that is already in use, a new unique name will be created to avoid the conflict. The callback is your opportunity to see what name was actually chosen. |
| user_data | This pointer will be passed back to you in the callback_function. This may be NULL. |
| void BNSD_UnregisterService | ( | struct BNSD_Registration * | registration_service | ) |
Stops advertising an existing service and frees the resources.
This will unregister a service you created with BNSD_RegisterService and free the resource.
| registration_service | The service you want to stop advertising. |
| struct BNSD_Discovery* BNSD_StartDiscovery | ( | const char * | service_type, |
| const char * | domain, | ||
| uint32_t | flags, | ||
| BNSD_DiscoveryCallback | callback_function, | ||
| void * | user_data | ||
| ) |
Starts discovering all services that are currently advertised matching your critera.
Starts discovering all services that are currently advertised matching your critera. You will get a callback for each service that is advertised, and a callback for each services that was available but just stopped advertising.
| service_type | The service type followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The service type must be an underscore, followed by 1-15 characters, which may be letters, digits, or hyphens. The transport protocol must be "_tcp" or "_udp". New service types should be registered at http://www.dns-sd.org/ServiceTypes.html. Trailing dots are allowed (e.g. "_ftp._tcp.") This does not support subtypes. May not be NULL. |
| domain | You should pass NULL which will utilize defaults. Advanced use cases of specifying a domain other than "local" may not be cross-platform. Trailing dots are allowed. |
| flags | Reserved for future use. Pass 0 for now. |
| callback_function | The callback function that will be invoked for each service found. |
| user_data | This pointer will be passed back to you in the callback_function. This may be NULL. |
| void BNSD_StopDiscovery | ( | struct BNSD_Discovery * | discovery_service | ) |
Stops discovering services for the specific instance.
This stops discovering services created with BNSD_StartDiscovery and free the resource.
| discovery_service | The service you want to stop discovering. |
| struct BNSD_Resolve* BNSD_StartResolve | ( | const char * | service_name, |
| const char * | service_type, | ||
| const char * | domain, | ||
| uint32_t | flags, | ||
| uint32_t | time_out, | ||
| BNSD_ResolveCallback | callback_function, | ||
| void * | user_data | ||
| ) |
Starts resolving the service you request.
Starts resolving the service you request. A callback will give you information about your service. As long as the resolve is running, you may receive additional callbacks when information changes. To cut down on unnecessary network traffic, you should call BNSD_StopResolve once you have all the information you need. However, if you are doing advanced things to use DNS TXT Records to broadcast changes, keeping the resolve going is the appropriate thing to do. Optionally, you may specify a time_out value which will give you a callback at that time. After the time_out, additional callbacks will be suppressed for convenience. However, network resources may still be active. So you are still responsible for calling BNSD_StopResolve after the time out.
| service_name | The name of the service to resolve. This is typically a service_name you got from a BNSD_DiscoveryCallback. |
| service_type | The service type followed by the protocol, separated by a dot (e.g. "_ftp._tcp"). The service type must be an underscore, followed by 1-15 characters, which may be letters, digits, or hyphens. The transport protocol must be "_tcp" or "_udp". New service types should be registered at http://www.dns-sd.org/ServiceTypes.html. Trailing dots are allowed (e.g. "_ftp._tcp.") This does not support subtypes. May not be NULL. This is typically a service_name you got from a BNSD_DiscoveryCallback. |
| domain | You should provide the value you got from BNSD_DiscoveryCallback or pass NULL. |
| flags | Reserved for future use. Pass 0 for now. |
| time_out | Passing a non-zero value will set up a callback in the specified number of seconds, that you want a callback to happen with the blurrr_error_code==BNSD_ERR_RESOLVE_TIMEOUT. This is provided as a convenince in case your requested service doesn't resolve (maybe the service died without alerting the network). Using a timeout is a convenient way to help you from keeping your app waiting forever for a resolve. When your callback happens, remember that you are still required to call BNSD_StopResolve to fully stop and clean up the resources. Pass 0 if you do not want a timeout. |
| callback_function | The callback function that will be invoked for the resolve. |
| user_data | This pointer will be passed back to you in the callback_function. This may be NULL. |
| void BNSD_StopResolve | ( | struct BNSD_Resolve * | resolve_service | ) |
Stops resolving services for the specific instance.
This stops resolving services created with BNSD_StartResolve and free the resource.
| resolve_service | The service you want to stop resolving. |