#include "dc/dc_Types.h"
#include "dc/dc_Error.h"
Defines | |
Configuration API | |
These APIs are used to configure the toolkit, especially devices. | |
#define | RANDOM_DEVICE_ID 0x7FFF |
If passed to dpws_create_device or dpws_create_custom_device as a local ID will make the default UUID randomly generated. | |
Configuration parameters setters macros | |
The following macro call configuration API using a syntax close to the parameter syntax. | |
#define | DPWS_SET_PTR_ATT(h, p, v) dpws_set_ptr_att(h,p,v) |
Macro to set the value of configurable object attribute of pointer type. | |
#define | DPWS_SET_STR_ATT(h, p, v) dpws_set_ptr_att(h,p,v) |
Macro to set the value of configurable object attribute of string type. | |
#define | DPWS_SET_INT_ATT(h, p, v) dpws_set_int_att(h,p,v) |
Macro to set the value of configurable object attribute of integer type. | |
#define | DPWS_SET_BOOL_ATT(h, p, v) dpws_set_int_att(h,p,v) |
Macro to set the value of configurable object attribute of boolean type. | |
#define | DPWS_ADD_PTR_ATT(h, p, v) dpws_add_ptr_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of pointer type. | |
#define | DPWS_ADD_STR_ATT(h, p, v) dpws_add_ptr_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of string type. | |
#define | DPWS_ADD_INT_ATT(h, p, v) dpws_add_int_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of integer type. | |
#define | DPWS_ADD_BOOL_ATT(h, p, v) dpws_add_int_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of boolean type. | |
registry/toolkit configuration parameters | |
#define | DC_REGISTRY_HANDLE -1 |
The reserved handle for the registry. | |
#define | DC_TOOLKIT_HANDLE -1 |
The reserved handle for the "toolkit". | |
#define | DPWS_INT_BOOT_SEQ 1 |
Host boot sequence. | |
#define | DPWS_PTR_CALLBACK_DEVICE_METADATA 2 |
metadata_cbk called when discovery device metadata version changes. | |
#define | DPWS_INT_HTTP_PORT 3 |
Toolkit HTTP server port. | |
#define | DPWS_BOOL_TCP_LISTEN 4 |
If DC_FALSE, the HTTP listener is not started. | |
#define | DPWS_INT_HTTP_BACKLOG 5 |
The number of TCP pending connection requests for the HTTP listener. | |
toolkit configuration parameters | |
#define | DPWS_STR_PREFERRED_LANG 10 |
The "xml:lang format" value that will help the toolkit to select the device metadata language when several are retrieved. | |
#define | DPWS_BOOL_BP1_1_COMPATIBILITY 11 |
When DC_TRUE, WS-Addressing headers are not required which ensures the main runtime compatibility feature for WSI Basic Profile 1.1 support. | |
device instance, service class parameters | |
#define | DPWS_PTR_TYPE 20 |
Device or service class types. | |
#define | DPWS_PTR_PREFIXED_TYPE 21 |
Device or service class types. | |
#define | DPWS_PTR_WSDL 22 |
Device or service class WSDL references. | |
device model, service class parameters | |
#define | DPWS_STR_ID 30 |
String ID for device model and service class objects. | |
device, service class and endpoint parameters | |
#define | DPWS_PTR_FAULT_FUNCTION 40 |
dispatch_cbk that can be set on device, service class or endpoint and will be called when a fault is received. | |
#define | DPWS_PTR_CALLBACK_EVENT_END 41 |
event_end_cbk that can be set on device, service class or endpoint and will be called when a WS-Eventing subscription expires in unexpected manner. | |
#define | DPWS_PTR_HANDLING_FUNCTION 42 |
dispatch_cbk that can be set on device, service class or endpoint and will be called when a SOAP message is received. | |
device model and instance parameters | |
#define | DPWS_PTR_MODEL_NAME 50 |
Mandatory device model name. | |
#define | DPWS_STR_MODEL_NUMBER 51 |
Model number as a string. | |
#define | DPWS_STR_MODEL_URL 52 |
Model URL as a string. | |
#define | DPWS_STR_PRESENTATION_URL 53 |
Presentation URL as a string. | |
#define | DPWS_PTR_MANUFACTURER 54 |
Mandatory device manufacturer. | |
#define | DPWS_STR_MANUFACTURER_URL 55 |
Manufacturer URL as a string. | |
device or service port parameters | |
#define | DPWS_STR_ADDRESS 60 |
Optional relative or absolute URL. | |
service instance parameters | |
#define | DPWS_STR_SERVICE_ID 70 |
Service ID. | |
#define | DPWS_INT_CLASS_HREF 100 |
Read-only class handle reference for service instances. | |
device instance parameters | |
#define | DPWS_INT_METADATA_VERSION 80 |
Mandatory device metadata version. | |
#define | DPWS_STR_DEVICE_ID 81 |
Device UUID. | |
#define | DPWS_STR_SCOPE 82 |
Optional. | |
#define | DPWS_PTR_FRIENDLY_NAME 83 |
Mandatory and potentially multivalued struct localized_string for device friendly name. | |
#define | DPWS_STR_FIRMWARE_VERSION 84 |
Device firmware version as a string. | |
#define | DPWS_STR_SERIAL_NUMBER 85 |
Device serial number as a string. | |
device, service instance and class parameters | |
#define | DPWS_PTR_USER_DATA 90 |
Optional pointer on free user data that can be retrieved in service implementation function. | |
Discovery cache configuration parameters | |
#define | DC_CACHE_HANDLE -2 |
The reserved handle for the cache. | |
#define | DPWS_PTR_CACHE_FILTER 200 |
Specifies what devices should be stored in the cache. | |
#define | DPWS_PTR_CALLBACK_HELLO 201 |
A discovery_cbk function called when a device matching the cache filter has joined the network and was added to the cache. | |
#define | DPWS_PTR_CALLBACK_BYE 202 |
A discovery_cbk function called when a device leaves the cache. | |
#define | DPWS_INT_MAX_DEVICE_PROXIES 203 |
Maximum number of "unused" device proxies that the cache can contain. | |
Subscription management parameters | |
#define | DC_SUBSC_MANAGER_HANDLE -3 |
The reserved handle for the WS-Eventing. | |
#define | DPWS_INT_MAX_SUBSC_NB 301 |
The maximum number of subscriptions. | |
#define | DPWS_STR_MAX_SUBSC_DURATION 302 |
Maximum duration for WS-Eventing subscriptions as an XML duration. | |
#define | DPWS_INT_MAX_SUBSC_DURATION 303 |
Maximum duration for WS-Eventing subscriptions in seconds. | |
Functions | |
DC_RT_FMAC1 short | dpws_create_device_model () |
Creates an empty device model object. | |
DC_RT_FMAC1 short | dpws_create_service_class () |
Creates an empty service class object. | |
DC_RT_FMAC1 int | dpws_register_service_class (short device_model_href, short service_class_href) |
Associates a service class to a device model. | |
DC_RT_FMAC1 short | dpws_create_device (unsigned short local_id, short model_href) |
Creates a device instance object with all associated hosted services in one API call. | |
DC_RT_FMAC1 short | dpws_create_custom_device (unsigned short local_id, short model_href) |
Creates a device instance object without hosted services. | |
DC_RT_FMAC1 short | dpws_create_hosted_service (short device_href, short service_class_href) |
Creates a hosted service (and its associated HTTP service port) on a device instance. | |
DC_RT_FMAC1 short | dpws_create_service_port () |
Creates a new service port on the default HTTP listener. | |
DC_RT_FMAC1 int | dpws_bind_service (short hrefService, short hrefServicePort) |
Publishes a service endpoint on a specific address (service port). | |
DC_RT_FMAC1 short | dpws_create_endpoint () |
Creates an endpoint and a bound service port. | |
DC_RT_FMAC1 short | dpws_get_device_model_handle (char *id) |
Retrieves a device model handle by its id attribute. | |
DC_RT_FMAC1 short | dpws_get_service_class_handle (char *id) |
Retrieves a service class handle by its id attribute. | |
DC_RT_FMAC1 int | dpws_get_service_class_handles (short *hrefs, int *len) |
Retrieves all service class handle references. | |
DC_RT_FMAC1 short | dpws_get_device_handle (char *uuid) |
Retrieves a device handle by its uuid. | |
DC_RT_FMAC1 int | dpws_get_device_handles (short *hrefs, int *len) |
Retrieves all configured device handle references. | |
DC_RT_FMAC1 short | dpws_get_service_handle (short device_href, char *service_id) |
Retrieves a hosted service handle by its service identifier. | |
DC_RT_FMAC1 short | dpws_get_service_by_class (short device_href, short service_class_href) |
Retrieves a hosted service handle by its service class. | |
DC_RT_FMAC1 int | dpws_get_services_by_class (short hrefClass, short *hrefs, int *len) |
Retrieves all service implementations of a class. | |
DC_RT_FMAC1 short | dpws_get_service_device (short href) |
Retrieves the device hosting a service. | |
DC_RT_FMAC1 int | dpws_get_service_handles (short device_href, short *hrefs, int *len) |
Retrieves service handles attached to a device instance. | |
DC_RT_FMAC1 int | dpws_get_service_port_handles (short endpoint_href, short *hrefs, int *len) |
Retrieves service port handle references bound to a local device or service endpoint. | |
DC_RT_FMAC1 short | dpws_get_default_service_port (short endpoint_href) |
Get the default service port handle reference bound to a device or service endpoint. | |
DC_RT_FMAC1 int | dpws_release_handle (short href) |
Releases a toolkit configuration object handle when not needed anymore by the user. | |
DC_RT_FMAC1 int | dpws_release_handles (short *hrefs, int len) |
Releases a toolkit configuration objects handle array when not needed anymore by the user. | |
DC_RT_FMAC1 short | dpws_get_handle_use_count (short href) |
Retrieves the number of user of a toolkit configuration object. | |
DC_RT_FMAC1 struct wsa_endpoint_ref * | dpws_get_local_endpoint_ref (short service_port_href) |
Allocates and initialize a wsa_endpoint_ref structure for a service port attached to a device, an hosted service or any local endpoint. | |
DC_RT_FMAC1 char * | dpws_get_transport_address (short href_service_port) |
Builds the default physical address for a local service port. | |
DC_RT_FMAC1 char ** | dpws_get_transport_addresses (short href_service_port, int *res_size) |
Retrieves the physical addresses for a local service port corresponding to all the IP addresses selected for the toolkit. | |
DC_RT_FMAC1 int | dpws_delete_hosted_service (short service_href) |
Deletes a hosted service. | |
DC_RT_FMAC1 int | dpws_enable_device (short device_href) |
Make a device available on the network. | |
DC_RT_FMAC1 int | dpws_disable_device (short device_href) |
Removes a device from the network. | |
DC_RT_FMAC1 short | dpws_clone_device (short href) |
Clones an online device in order to be able to perform "hot-configuration" on the device. | |
DC_RT_FMAC1 int | dpws_replace_device (short href_online, short href_offline) |
Substitutes an online device with an offline one. | |
DC_RT_FMAC1 int SOAP_FMAC2 | dpws_remove_subscriber (short event_source, struct wsa_endpoint_ref *notify_to) |
Removes all the subscriptions attached to a service endpoint for a given notification address. | |
DC_RT_FMAC1 int | dpws_set_ptr_att (short href, int att, const void *value) |
Used to set a server object attribute value for pointer parameter types (strings included). | |
DC_RT_FMAC1 int | dpws_set_int_att (short href, int att, unsigned long value) |
Used to set a server object attribute value for integer types (boolean included). | |
DC_RT_FMAC1 int | dpws_add_ptr_att (short href, int att, const void *value) |
Used to add a server object attribute value for pointer parameter types (strings included) when this attribute is multivalued. | |
DC_RT_FMAC1 int | dpws_add_int_att (short href, int att, unsigned long value) |
Used to add a server object attribute value for integer types (boolean included) when this attribute is multivalued. | |
DC_RT_FMAC1 void * | dpws_get_ptr_att (short href, int att) |
Returns server object attributes for pointer types (string or not) attributes. | |
DC_RT_FMAC1 int | dpws_get_att_count (short href, int att) |
Returns the number of attributes attached to a server object. | |
DC_RT_FMAC1 void * | dpws_get_ptr_att_item (short href, int att, int index) |
Returns a specific instance of a multivalued server object attributes for pointer types (string or not) attributes. | |
DC_RT_FMAC1 unsigned long | dpws_get_int_att (short href, int att) |
Returns server object attributes of integer type (or boolean). | |
Initialization API | |
For DPWS stack startup/shutdown. | |
DC_RT_FMAC1 int | dpws_init () |
DPWS tookit initialization function (IPv4 mode). | |
DC_RT_FMAC1 int | dpws_init6 () |
DPWS tookit initialization function (IPv6 mode). | |
DC_RT_FMAC1 int | dpws_init_ex (dc_ip_filter_t *selector, const char *hostname, int versions) |
Full-feature DPWS tookit initialization function. | |
DC_RT_FMAC1 int | dpws_shutdown () |
Shutdowns the DPWS toolkit. | |
General usage utilities | |
These APIs can be used both for client & server operations. | |
DC_RT_FMAC1 int | dpws_end (struct dpws *dpws) |
Clears structures and free dynamically allocated memory used for request processing. | |
DC_RT_FMAC1 int | dpws_get_error (struct dpws *dpws) |
Returns the last DPWS or gSOAP runtime error. | |
DC_RT_FMAC1 const char * | dpws_get_error_msg (struct dpws *dpws) |
Gets a message for a SOAP fault or a DPWS/gSOAP error that has previously occurred. | |
DC_RT_FMAC1 void | dpws_default_wsa_endpoint_ref (struct wsa_endpoint_ref *endpoint_ref) |
Initialize a wsa_endpoint_ref structure that the user may use for a subsequent API call. | |
DC_RT_FMAC1 struct wsa_endpoint_ref * | dpws_create_device_endpoint_ref (char *uuid) |
Allocates and initialize a wsa_endpoint_ref structure for a device. | |
DC_RT_FMAC1 struct wsa_endpoint_ref * | dpws_endpoint_ref_dup (struct wsa_endpoint_ref *endpoint) |
Creates a deep copy of a wsa_endpoint_ref structure on DPWS library heap. | |
DC_RT_FMAC1 struct wsa_endpoint_ref * | dpws_endpoint_ref_copy (struct wsa_endpoint_ref *dest, struct wsa_endpoint_ref *src) |
Copy of a wsa_endpoint_ref structure to a provided destination. | |
DC_RT_FMAC1 void | dpws_free (void *buffer) |
Frees a string or any buffer allocated on the DPWS library heap. | |
DC_RT_FMAC1 void | dpws_endpoint_ref_content_free (struct wsa_endpoint_ref *endpoint) |
Frees the contents of an endpoint reference. | |
DC_RT_FMAC1 void | dpws_endpoint_ref_free (struct wsa_endpoint_ref *endpoint) |
Frees an endpoint reference and its contents. | |
DC_RT_FMAC1 void | dpws_endpoint_ref_array_free (struct wsa_endpoint_ref **endpoints, int nb_endpoints) |
Frees an endpoint reference array and its contents. | |
Server Runtime API | |
These APIs allow to:
| |
#define | DC_LISTENER_HTTP 0x1 |
HTTP listener. | |
#define | DC_LISTENER_DISCOVERY 0x2 |
WS-Discovery listener. | |
enum | fault_value_t { SENDER_FAULT_VALUE = 0, RECEIVER_FAULT_VALUE = 1 } |
Enumeration to use with dpws_fault. More... | |
DC_RT_FMAC1 int | dpws_server_init (struct dpws *dpws, struct wsa_endpoint_ref *source) |
Initialize the dpws structure and perform server-side initialization. | |
DC_RT_FMAC1 int | dpws_server_init_ex (struct dpws *dpws, struct wsa_endpoint_ref *source, int listeners, int bind_flags, int backlog) |
Initialize the dpws structure and perform server-side initialization. | |
DC_RT_FMAC1 int | dpws_accept (struct dpws *dpws) |
Blocks and wait for an incoming SOAP message or expired timer. | |
DC_RT_FMAC1 int | dpws_accept_thr (struct dpws *dpws, struct dpws *dpws_thr) |
Blocks and wait for an incoming SOAP message or expired timer. | |
DC_RT_FMAC1 int | dpws_serve (struct dpws *dpws) |
Handles a request message. | |
DC_RT_FMAC1 int | dpws_stop_server (long delay_ms) |
Stops smoothly the locally running server for multi-thread servers. | |
DC_RT_FMAC1 int | dpws_stop_server_no_wait () |
Stops smoothly the locally running server. | |
DC_RT_FMAC1 int | dpws_join_network (unsigned long boot_seq) |
This API must be called after the network has been stopped (unplugged cable for instance) while the DPWS server was running to send hello messages for enabled devices. | |
DC_RT_FMAC1 void * | dpws_get_endpoint_user_data (struct dpws *dpws) |
Retrieves the user data associated to the endpoint that received the message. | |
DC_RT_FMAC1 void * | dpws_get_device_user_data (struct dpws *dpws) |
Retrieves the user data associated to the device instance that received the message. | |
DC_RT_FMAC1 void * | dpws_get_service_class_user_data (struct dpws *dpws) |
Retrieves the user data associated to the service class of the endpoint that received the message. | |
DC_RT_FMAC1 void * | dpws_malloc (struct dpws *dpws, size_t size) |
Allocate message transient memory. | |
DC_RT_FMAC1 int | dpws_fault (struct dpws *dpws, fault_value_t value, const char *faultstring, const char *subcode, const char *detail) |
Prepares a SOAP 1.2 fault. | |
DC_RT_FMAC1 int | dpws_server_shutdown (struct dpws *dpws) |
Resets server configuration. | |
Client Runtime API | |
These APIs allow:
| |
#define | WSD_DEFAULT_SCOPE "http://schemas.xmlsoap.org/ws/2005/04/discovery/adhoc" |
WS-Discovery implicit default scope. | |
#define | dpws_get_service dpws_get_services |
#define | dpws_get_default_endpoint_reference dpws_get_default_endpoint_ref |
#define | dpws_get_endpoint_references dpws_get_endpoint_refs |
enum | proxy_type_t { UNKNOWN_PROXY_TYPE = 0, DEVICE_PROXY_TYPE = 1, SERVICE_PROXY_TYPE = 2 } |
Client proxy type enumeration used with dpws_get_proxy_type. More... | |
DC_RT_FMAC1 int | dpws_client_init (struct dpws *dpws, struct wsa_endpoint_ref *source) |
Initialize the dpws structure and perform one-time client-side initialisation. | |
DC_RT_FMAC1 short * | dpws_lookup (struct dpws *dpws, char *ns, char *type, char *scope, int *res_size) |
Retrieves one or several device proxies basing on a type and a scope. | |
DC_RT_FMAC1 short * | dpws_lookup_ex (struct dpws *dpws, discovery_filter_t *filter, int f_size, int *res_size, unsigned int time_out, cache_mode_t mode) |
Retrieves one or several device endpoints basing on types and scopes. | |
DC_RT_FMAC1 short | dpws_lookup_by_id (struct dpws *dpws, const char *uuid) |
Checks a DPWS device is available on the local network and retrieve its proxy. | |
DC_RT_FMAC1 short | dpws_probe_address (struct dpws *dpws, char *address, char *ns, char *type, char *scope) |
Retrieves a device proxy checking a physical address matches a type and a scope. | |
DC_RT_FMAC1 short | dpws_probe_address_ex (struct dpws *dpws, char *address, discovery_filter_t *filter) |
Retrieves a device endpoint checking a physical address matches a set of types and scopes. | |
DC_RT_FMAC1 short * | dpws_get_services (struct dpws *dpws, short href_device, char *ns, char *port_type, int *res_size) |
Retrieve one or several service proxies basing on a device endpoint and a type. | |
DC_RT_FMAC1 short | dpws_get_service_by_id (struct dpws *dpws, short href_device, char *id) |
Retrieve a service proxy based on its service ID. | |
DC_RT_FMAC1 int | dpws_pin_proxy (short href_proxy) |
Increase the use counter of a cached device or service so that is cannot be freed by the toolkit even if invalid from the cache point of view. | |
DC_RT_FMAC1 int | dpws_release_proxy (short href_proxy) |
Decrease the use counter of a cached device or service so that it can be freed by the toolkit if invalid from the cache point of view. | |
DC_RT_FMAC1 proxy_type_t | dpws_get_proxy_type (short href_proxy) |
Return the type of proxy returned by the dpws_get_services. | |
DC_RT_FMAC1 short | dpws_get_proxy_by_id (char *id) |
Retrieves a cached proxy handle reference basing on an id. | |
DC_RT_FMAC1 short | dpws_get_proxy_by_address (char *address) |
Retrieves a cached proxy handle reference based on a physical address. | |
DC_RT_FMAC1 DC_BOOL | dpws_check_proxy (short href_proxy) |
Check if a cached device or service is still valid from the cache point of view. | |
DC_RT_FMAC1 int | dpws_invalidate_proxy (short href) |
Removes a device or service proxy from the cache. | |
DC_RT_FMAC1 DC_BOOL | dpws_device_proxy_match (short href_device, discovery_filter_t *criterion) |
Checks a device matches a given WS-Discovery match criterion. | |
DC_RT_FMAC1 unsigned long | dpws_cache_get_device_metadata_version (short href_device) |
Retrieves the metadata version of a cached device proxy. | |
DC_RT_FMAC1 char ** | dpws_cache_get_scopes (struct dpws *dpws, short href_device) |
Retrieves the scopes of a device in the cache. | |
DC_RT_FMAC1 char * | dpws_cache_get_uuid (struct dpws *dpws, short href_device) |
Retrieves the uuid of a device in the cache. | |
DC_RT_FMAC1 struct qname ** | dpws_cache_get_types (struct dpws *dpws, short href_proxy) |
Retrieves the port types for a device or service proxy lying in the cache. | |
DC_RT_FMAC1 char ** | dpws_cache_get_device_transport_addresses (struct dpws *dpws, short href_device, int *res_size) |
Retrieves in the cache the URLs for a device. | |
DC_RT_FMAC1 struct wsa_endpoint_ref * | dpws_get_default_endpoint_ref (struct dpws *dpws, short href_proxy) |
Gets the default endpoint reference for a device or service proxy. | |
DC_RT_FMAC1 struct wsa_endpoint_ref ** | dpws_get_endpoint_refs (struct dpws *dpws, short href_proxy, int *res_size) |
Gets all the endpoint references retrieved for a device or service proxy. | |
DC_RT_FMAC1 struct device_metadata * | dpws_get_device_metadata (struct dpws *dpws, short href_device) |
Retrieves the whole DPWS metadata for a device. | |
DC_RT_FMAC1 struct service_metadata * | dpws_get_service_metadata (struct dpws *dpws, short href_service) |
Retrieves the service DPWS metadata for a hosted service. | |
DC_RT_FMAC1 short | dpws_get_host_device_proxy (short href_service) |
Retrieves in the cache the hosting device proxy of a hosted service. | |
DC_RT_FMAC1 struct wsa_endpoint_ref * | dpws_event_subscribe (struct dpws *dpws, struct wsa_endpoint_ref *event_source, struct wsa_endpoint_ref *notify_to, struct wsa_endpoint_ref *end_to, char **filter, char **expiration) |
Subscribes to a WS-Eventing event source. | |
DC_RT_FMAC1 struct wsa_endpoint_ref * | dpws_event_subscribe_ex (struct dpws *dpws, struct wsa_endpoint_ref *event_source, short href_notify_to, short href_end_to, char **filter, char **expiration) |
Subscribes to a WS-Eventing event source for a local event sink. | |
DC_RT_FMAC1 char * | dpws_event_renew (struct dpws *dpws, struct wsa_endpoint_ref *subscription_manager, char *expiration) |
Renews a subscription to a WS-Eventing event source. | |
DC_RT_FMAC1 char * | dpws_event_status (struct dpws *dpws, struct wsa_endpoint_ref *subscription_manager) |
Gets the remaining duration for a subscription to a WS-Eventing event source. | |
DC_RT_FMAC1 int | dpws_event_unsubscribe (struct dpws *dpws, struct wsa_endpoint_ref *subscription_manager) |
Cancel a running subscription to a WS-Eventing event source. |
Most application using the standard DPWS features should only include this file.
#define RANDOM_DEVICE_ID 0x7FFF |
If passed to dpws_create_device or dpws_create_custom_device as a local ID will make the default UUID randomly generated.
#define DPWS_SET_PTR_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_set_ptr_att(h,p,v) |
Macro to set the value of configurable object attribute of pointer type.
#define DPWS_SET_STR_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_set_ptr_att(h,p,v) |
Macro to set the value of configurable object attribute of string type.
#define DPWS_SET_INT_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_set_int_att(h,p,v) |
Macro to set the value of configurable object attribute of integer type.
#define DPWS_SET_BOOL_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_set_int_att(h,p,v) |
Macro to set the value of configurable object attribute of boolean type.
#define DPWS_ADD_PTR_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_add_ptr_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of pointer type.
#define DPWS_ADD_STR_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_add_ptr_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of string type.
#define DPWS_ADD_INT_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_add_int_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of integer type.
#define DPWS_ADD_BOOL_ATT | ( | h, | |||
p, | |||||
v | ) | dpws_add_int_att(h,p,v) |
Macro to add a value to a configurable object multi-valued attribute of boolean type.
#define DC_REGISTRY_HANDLE -1 |
The reserved handle for the registry.
#define DC_TOOLKIT_HANDLE -1 |
The reserved handle for the "toolkit".
Supplied for backward compatibility.
#define DPWS_INT_BOOT_SEQ 1 |
Host boot sequence.
Mandatory.
#define DPWS_PTR_CALLBACK_DEVICE_METADATA 2 |
metadata_cbk called when discovery device metadata version changes.
Optional.
#define DPWS_INT_HTTP_PORT 3 |
Toolkit HTTP server port.
Optional. Default is 80.
#define DPWS_BOOL_TCP_LISTEN 4 |
If DC_FALSE, the HTTP listener is not started.
Optional (DC_TRUE if missing).
#define DPWS_INT_HTTP_BACKLOG 5 |
The number of TCP pending connection requests for the HTTP listener.
Optional (default is 10).
#define DPWS_STR_PREFERRED_LANG 10 |
The "xml:lang format" value that will help the toolkit to select the device metadata language when several are retrieved.
Optional.
#define DPWS_BOOL_BP1_1_COMPATIBILITY 11 |
When DC_TRUE, WS-Addressing headers are not required which ensures the main runtime compatibility feature for WSI Basic Profile 1.1 support.
Optional. Default is false.
#define DPWS_PTR_TYPE 20 |
Device or service class types.
qname struct C type. Multivalued and mandatory.
#define DPWS_PTR_PREFIXED_TYPE 21 |
Device or service class types.
struct prefixed_qname C type. Multivalued and mandatory.
#define DPWS_PTR_WSDL 22 |
Device or service class WSDL references.
struct wsdl_info C type. Multivalued and mandatory.
#define DPWS_STR_ID 30 |
String ID for device model and service class objects.
Optional. default: string form of the object handle reference
#define DPWS_PTR_FAULT_FUNCTION 40 |
dispatch_cbk that can be set on device, service class or endpoint and will be called when a fault is received.
Optional.
#define DPWS_PTR_CALLBACK_EVENT_END 41 |
event_end_cbk that can be set on device, service class or endpoint and will be called when a WS-Eventing subscription expires in unexpected manner.
Optional.
#define DPWS_PTR_HANDLING_FUNCTION 42 |
dispatch_cbk that can be set on device, service class or endpoint and will be called when a SOAP message is received.
Multivalued and optional.
#define DPWS_PTR_MODEL_NAME 50 |
Mandatory device model name.
Multivalued. struct localized_string.
#define DPWS_STR_MODEL_NUMBER 51 |
Model number as a string.
Optional.
#define DPWS_STR_MODEL_URL 52 |
Model URL as a string.
Optional.
#define DPWS_STR_PRESENTATION_URL 53 |
Presentation URL as a string.
Optional but often used for device HTTP page for instance by Windows Vista.
#define DPWS_PTR_MANUFACTURER 54 |
Mandatory device manufacturer.
Multivalued. struct localized_string.
#define DPWS_STR_MANUFACTURER_URL 55 |
Manufacturer URL as a string.
Optional.
#define DPWS_STR_ADDRESS 60 |
Optional relative or absolute URL.
If absolute : service may not be performed by the built-in HTTP server. Default: URL made of device IP + generated UUID
#define DPWS_STR_SERVICE_ID 70 |
Service ID.
Optional. Default: service class ID
#define DPWS_INT_CLASS_HREF 100 |
Read-only class handle reference for service instances.
#define DPWS_INT_METADATA_VERSION 80 |
Mandatory device metadata version.
Should be incremented every time device metadata changes.
#define DPWS_STR_DEVICE_ID 81 |
Device UUID.
Optional (generated if missing).
#define DPWS_STR_SCOPE 82 |
Optional.
Multivalued. Default is "http://schemas.xmlsoap.org/ws/2004/02/discovery/adhoc".
#define DPWS_PTR_FRIENDLY_NAME 83 |
Mandatory and potentially multivalued struct localized_string for device friendly name.
#define DPWS_STR_FIRMWARE_VERSION 84 |
Device firmware version as a string.
Optional.
#define DPWS_STR_SERIAL_NUMBER 85 |
Device serial number as a string.
Optional.
#define DPWS_PTR_USER_DATA 90 |
Optional pointer on free user data that can be retrieved in service implementation function.
#define DC_CACHE_HANDLE -2 |
The reserved handle for the cache.
#define DPWS_PTR_CACHE_FILTER 200 |
Specifies what devices should be stored in the cache.
Also affects the hello callback. Optional, multivalued. Contains discovery_filter_t structures.
#define DPWS_PTR_CALLBACK_HELLO 201 |
A discovery_cbk function called when a device matching the cache filter has joined the network and was added to the cache.
Optional.
#define DPWS_PTR_CALLBACK_BYE 202 |
A discovery_cbk function called when a device leaves the cache.
Optional.
#define DPWS_INT_MAX_DEVICE_PROXIES 203 |
Maximum number of "unused" device proxies that the cache can contain.
Unused proxies are devices that are not hold by the user through the API. When the maximum number of proxies is reached, a LRU algorithm removes the oldest one. Optional. Default value is unlimited (2e16).
#define DC_SUBSC_MANAGER_HANDLE -3 |
The reserved handle for the WS-Eventing.
#define DPWS_INT_MAX_SUBSC_NB 301 |
The maximum number of subscriptions.
If exceeded, subscription is refused. Optional. Default is almost unlimited (0xFFFFFFFF)
#define DPWS_STR_MAX_SUBSC_DURATION 302 |
Maximum duration for WS-Eventing subscriptions as an XML duration.
Optional. Default is "P1D" (1 day). Cannot be retrieved: use the integer representation.
#define DPWS_INT_MAX_SUBSC_DURATION 303 |
Maximum duration for WS-Eventing subscriptions in seconds.
Optional. Default is 86400 (1 day).
#define DC_LISTENER_HTTP 0x1 |
HTTP listener.
#define DC_LISTENER_DISCOVERY 0x2 |
WS-Discovery listener.
#define WSD_DEFAULT_SCOPE "http://schemas.xmlsoap.org/ws/2005/04/discovery/adhoc" |
WS-Discovery implicit default scope.
enum fault_value_t |
enum proxy_type_t |
DC_RT_FMAC1 int dpws_init | ( | ) |
DPWS tookit initialization function (IPv4 mode).
This function must be called before any other API call. Using this API makes the toolkit select one IP address among the one eligible (IPv4, not loopback). For multiple interface & protocol support, please use dpws_init_ex.
DC_RT_FMAC1 int dpws_init6 | ( | ) |
DPWS tookit initialization function (IPv6 mode).
This function must be called before any other API call. Using this API makes the toolkit select one IP address among the one eligible (IPv6, not loopback). For multiple interface & protocol support, please use dpws_init_ex.
DC_RT_FMAC1 int dpws_init_ex | ( | dc_ip_filter_t * | selector, | |
const char * | hostname, | |||
int | versions | |||
) |
Full-feature DPWS tookit initialization function.
This function must be called before any other API call and allows multiple interface & protocol support.
selector | A structure containing filtering information to select network interfaces and IP addresses for the toolkit. | |
hostname | If supplied (nullable), the DNS name will be used in published transport addresses instead of IP addresses. | |
versions | a bit set of supported DPWS versions (DPWS10_VERSION, DPWS11_VERSION ...). DPWS_DEFAULT_VERSION designates an implementation-specific default value. |
DC_RT_FMAC1 int dpws_shutdown | ( | ) |
Shutdowns the DPWS toolkit.
After this call, all DPWS toolkit resources are freed and a call to dpws_init() must be performed to be able to operate again. This api is called in the Windows DLL version delivery when a process stops to use the DLL.
DC_RT_FMAC1 short dpws_create_device_model | ( | ) |
Creates an empty device model object.
DC_RT_FMAC1 short dpws_create_service_class | ( | ) |
Creates an empty service class object.
A service class is immutable when the server loop is running and it is used by a hosted service.
DC_RT_FMAC1 int dpws_register_service_class | ( | short | device_model_href, | |
short | service_class_href | |||
) |
Associates a service class to a device model.
Devices that will be created from the device model will host one service by service class registered to the device model. If the registration is not performed, hosted services will have to be created manually using dpws_create_hosted_service.
device_model_href | The device class model reference. | |
service_class_href | The service class handle reference. |
DC_RT_FMAC1 short dpws_create_device | ( | unsigned short | local_id, | |
short | model_href | |||
) |
Creates a device instance object with all associated hosted services in one API call.
This function creates an operational device object that will host a set of services corresponding to the service classes registered to the model of the device. Each service created will also have its own HTTP service port to which is will be bound. Note that the model is used as a template that will not be used anymore after device creation.
local_id | A numeric identifier for the device instance that, with the listening port and the MAC address, will be used to generate the stable device logical address (i.e., the UUID). Note that passing RANDOM_DEVICE_ID means that the UUID will be generated and that the UUID should be set to the same value thanks to the API during the next device configuration stage. | |
model_href | The device model handle reference. |
DC_RT_FMAC1 short dpws_create_custom_device | ( | unsigned short | local_id, | |
short | model_href | |||
) |
Creates a device instance object without hosted services.
This function creates an operational device object that host no services. The hosted services can be added later with the dpws_create_hosted_service API. Note that the model is used as a template that will not be used anymore after device creation.
local_id | A numeric identifier for the device instance that, with the listening port and the MAC address, will be used to generate the stable device logical address (i.e., the UUID). Note that passing RANDOM_DEVICE_ID means that the UUID will be generated and that the UUID should be set to the same value thanks to the API during the next device configuration stage. | |
model_href | The device model handle reference. -1 (no model), is accepted. |
DC_RT_FMAC1 short dpws_create_hosted_service | ( | short | device_href, | |
short | service_class_href | |||
) |
Creates a hosted service (and its associated HTTP service port) on a device instance.
The hosted service can only be added if that service class is registered to the class of the device. The service is created with the service class identifier as identifier. The service id attribute is an attribute that can be overwritten later.
device_href | The device instance handle reference. | |
service_class_href | The service class handle reference. |
DC_RT_FMAC1 short dpws_create_service_port | ( | ) |
Creates a new service port on the default HTTP listener.
A default, HTTP address is created for the port with the toolkit IP address and port plus a generated UUID which can be superseded by any absolute or relative URL by setting the DPWS_STR_ADDRESS parameter on the server object.
DC_RT_FMAC1 int dpws_bind_service | ( | short | hrefService, | |
short | hrefServicePort | |||
) |
Publishes a service endpoint on a specific address (service port).
hrefService | The service endpoint handle reference. | |
hrefServicePort | The service port handle reference. |
DC_RT_FMAC1 short dpws_create_endpoint | ( | ) |
Creates an endpoint and a bound service port.
Services (and then devices) are endpoints, from the DPWS specification point of vue. An endpoint can be considered as a service which is not hosted, i.e., which is not advertized in device's metadata. The endpoint is a kind of service which can be configured like a service class since its main use is to register handlers on it in order to receive events or asynchronous responses. An endpoint reference can be retrieved using dpws_get_local_endpoint_ref
DC_RT_FMAC1 short dpws_get_device_model_handle | ( | char * | id | ) |
Retrieves a device model handle by its id attribute.
id | The device model id attribute. |
DC_RT_FMAC1 short dpws_get_service_class_handle | ( | char * | id | ) |
Retrieves a service class handle by its id attribute.
id | The service class id attribute. |
DC_RT_FMAC1 int dpws_get_service_class_handles | ( | short * | hrefs, | |
int * | len | |||
) |
Retrieves all service class handle references.
[in,out] | hrefs | A short array provided by the caller to receive results. Note that returned handles should be released after use. |
[in,out] | len | Must contain initially the length of the array hrefs. When the function returns it contains the number of results actually retrieved. |
DC_RT_FMAC1 short dpws_get_device_handle | ( | char * | uuid | ) |
Retrieves a device handle by its uuid.
This method may be used when a discovery event is received using the user callback and device data has to be retrieved. Looks only for devices being configured or enabled. Disabled or cloned devices cannot be retrieved with this API.
uuid | the device uuid. |
DC_RT_FMAC1 int dpws_get_device_handles | ( | short * | hrefs, | |
int * | len | |||
) |
Retrieves all configured device handle references.
The retrieved devices must have been enabled once. Clones are not retrieved.
[in,out] | hrefs | A short array provided by the caller to receive results. Note that returned handles should be released after use. |
[in,out] | len | Must contain initially the length of the array hrefs. When the function returns it contains the number of results actually retrieved. |
DC_RT_FMAC1 short dpws_get_service_handle | ( | short | device_href, | |
char * | service_id | |||
) |
Retrieves a hosted service handle by its service identifier.
This function may be used to retrieve a hosted service when the dpws_create_device opaque function was used to create a device.
device_href | The device instance handle reference. | |
service_id | the service identifier used as a key. |
DC_RT_FMAC1 short dpws_get_service_by_class | ( | short | device_href, | |
short | service_class_href | |||
) |
Retrieves a hosted service handle by its service class.
This function may be used to retrieve a hosted service when the dpws_create_device opaque function was used to create a device.
device_href | The device instance handle reference. | |
service_class_href | The service class handle reference used as a key. |
DC_RT_FMAC1 int dpws_get_services_by_class | ( | short | hrefClass, | |
short * | hrefs, | |||
int * | len | |||
) |
Retrieves all service implementations of a class.
hrefClass | The service class handle reference. | |
hrefs | An array to receive the result handle references. Note that returned handles should be released after use. | |
[in,out] | len | Initially contains the size of the results array. When the function returns, it contains the actual number of results found. |
DC_RT_FMAC1 short dpws_get_service_device | ( | short | href | ) |
Retrieves the device hosting a service.
href | The handle reference of the hosted service. |
DC_RT_FMAC1 int dpws_get_service_handles | ( | short | device_href, | |
short * | hrefs, | |||
int * | len | |||
) |
Retrieves service handles attached to a device instance.
This function may be used to retrieve a hosted services when the dpws_create_device opaque function was used to create a device.
device_href | The device instance handle reference. | |
[in,out] | hrefs | A short array provided by the caller to receive results. Note that returned handles should be released after use. |
[in,out] | len | Must contain initially the length of the array hrefs. When the function returns it contains the number of results actually retrieved. |
DC_RT_FMAC1 int dpws_get_service_port_handles | ( | short | endpoint_href, | |
short * | hrefs, | |||
int * | len | |||
) |
Retrieves service port handle references bound to a local device or service endpoint.
This function may be used to retrieve service ports when the dpws_create_device opaque function was used to create a device.
endpoint_href | The (service) endpoint handle reference. | |
[in,out] | hrefs | A short array provided by the caller to receive results. Note that returned handles should be released after use. |
[in,out] | len | Must contain initially the length of the array hrefs. When the function returns it contains the number of results actually retrieved. |
DC_RT_FMAC1 short dpws_get_default_service_port | ( | short | endpoint_href | ) |
Get the default service port handle reference bound to a device or service endpoint.
Practically the first HTTP service port.
endpoint_href | The (service) endpoint handle reference. |
DC_RT_FMAC1 int dpws_release_handle | ( | short | href | ) |
Releases a toolkit configuration object handle when not needed anymore by the user.
This is good practice to release object handles in order to avoid memory exhaustion. Practically, top-level object like device or service classes should be released but also object retrieved by API other than creation APIs.
href | The handle reference on the object to release. |
DC_RT_FMAC1 int dpws_release_handles | ( | short * | hrefs, | |
int | len | |||
) |
Releases a toolkit configuration objects handle array when not needed anymore by the user.
This is good practice to release object handles in order to avoid memory exhaustion. Practically, top-level object like device or service classes should be released but also object retrieved by API other than creation APIs.
hrefs | A short array that contains handle references. | |
len | Must contain the length of the array hrefs. |
DC_RT_FMAC1 short dpws_get_handle_use_count | ( | short | href | ) |
Retrieves the number of user of a toolkit configuration object.
href | The handle reference on the configuration object. |
DC_RT_FMAC1 struct wsa_endpoint_ref* dpws_get_local_endpoint_ref | ( | short | service_port_href | ) | [read] |
Allocates and initialize a wsa_endpoint_ref structure for a service port attached to a device, an hosted service or any local endpoint.
Must be called after the call to dpws_server_init(). NOTE: This API was designed to be used with dpws_event_subscribe which should be replaced with dpws_event_subscribe_ex and is then kept for backwards compatibility but is not suited to multiple interface & protocol support.
service_port_href | A service port handle reference. |
DC_RT_FMAC1 char* dpws_get_transport_address | ( | short | href_service_port | ) |
Builds the default physical address for a local service port.
Must be called after the call to dpws_server_init(). NOTE: The new dpws_get_transport_addresses API should be preferred to this API when the multiple network interface or protocol support is used. Kept for backwards compatibility.
href_service_port | The handle for a local service port. |
DC_RT_FMAC1 char** dpws_get_transport_addresses | ( | short | href_service_port, | |
int * | res_size | |||
) |
Retrieves the physical addresses for a local service port corresponding to all the IP addresses selected for the toolkit.
These addresses should normally be used for information purposes. Must be called after the call to one API of the dpws_server_init() family.
href_service_port | The handle for a local service port. | |
[out] | res_size | The number of addresses retrieved. |
DC_RT_FMAC1 int dpws_delete_hosted_service | ( | short | service_href | ) |
Deletes a hosted service.
Undeploys a hosted service. Must ne performed on an "offline" device.
service_href | The service handle reference. |
DC_RT_FMAC1 int dpws_enable_device | ( | short | device_href | ) |
Make a device available on the network.
This API schedules a Hello message that is sent if the server is running. Note that the device handle held by the DPWS registry in addition to the device creator. A hold on the device handle will be taken so the hold of the creator can be released (making it disposable if the device is disabled).
device_href | The device handle reference. |
DC_RT_FMAC1 int dpws_disable_device | ( | short | device_href | ) |
Removes a device from the network.
This API schedules a Bye message that is sent if the server is running. Note that the device handle is released by the DPWS registry making it held only by the device creator.
device_href | The device handle reference. |
DC_RT_FMAC1 short dpws_clone_device | ( | short | href | ) |
Clones an online device in order to be able to perform "hot-configuration" on the device.
The device created is a "deep" copy of the original in the sense that all attached objects are also cloned (hosted services, service ports) except service classes. Once configuration operations is performed on the offline cloned device, the original one can be replaced with the cloned one using dpws_clone_device.
href | The handle reference of the device to be cloned. |
DC_RT_FMAC1 int dpws_replace_device | ( | short | href_online, | |
short | href_offline | |||
) |
Substitutes an online device with an offline one.
All device online service ports are replaced by the new device ones. Note that the offline device UUID and metadata version will be overwritten with the online ones and a hello message sent (with an incremented metadata version) if necessary. A hold on the replacement device handle will be taken so the hold of the creator can be released (making it disposable if the device is disabled).
href_online | The handle reference of the online device that will be replaced. | |
href_offline | The substitution device handle reference. |
DC_RT_FMAC1 int SOAP_FMAC2 dpws_remove_subscriber | ( | short | event_source, | |
struct wsa_endpoint_ref * | notify_to | |||
) |
Removes all the subscriptions attached to a service endpoint for a given notification address.
This function can be used in conjunction with the fnotification_failure callback to get rid of invalid subscribers.
event_source | The handle reference on the service acting as the event source. | |
notify_to | The endpoint reference of the subscriber to be removed. |
DC_RT_FMAC1 int dpws_set_ptr_att | ( | short | href, | |
int | att, | |||
const void * | value | |||
) |
Used to set a server object attribute value for pointer parameter types (strings included).
If the attribute is multivalued, replace the existing attributes.
href | The server object handle reference. | |
att | The attribute identifier. | |
value | The parameter value. Must be of the appropriate type, depending on the attribute. |
DC_RT_FMAC1 int dpws_set_int_att | ( | short | href, | |
int | att, | |||
unsigned long | value | |||
) |
Used to set a server object attribute value for integer types (boolean included).
If the attribute is multivalued, replace the existing attributes.
href | The server object handle reference. | |
att | The attribute identifier. | |
value | The integer parameter value. |
DC_RT_FMAC1 int dpws_add_ptr_att | ( | short | href, | |
int | att, | |||
const void * | value | |||
) |
Used to add a server object attribute value for pointer parameter types (strings included) when this attribute is multivalued.
If the attribute is monovalued, replace the existing attribute.
href | The server object handle reference. | |
att | The attribute identifier. | |
value | The parameter value. Must be of the appropriate type, depending on the attribute. |
DC_RT_FMAC1 int dpws_add_int_att | ( | short | href, | |
int | att, | |||
unsigned long | value | |||
) |
Used to add a server object attribute value for integer types (boolean included) when this attribute is multivalued.
If the attribute is monovalued, replace the existing attribute.
href | The server object handle reference. | |
att | The attribute identifier. | |
value | The integer parameter value. |
DC_RT_FMAC1 void* dpws_get_ptr_att | ( | short | href, | |
int | att | |||
) |
Returns server object attributes for pointer types (string or not) attributes.
href | The server object handle reference. | |
att | The attribute identifier. |
DC_RT_FMAC1 int dpws_get_att_count | ( | short | href, | |
int | att | |||
) |
Returns the number of attributes attached to a server object.
href | The server object handle reference. | |
att | The attribute identifier. |
DC_RT_FMAC1 void* dpws_get_ptr_att_item | ( | short | href, | |
int | att, | |||
int | index | |||
) |
Returns a specific instance of a multivalued server object attributes for pointer types (string or not) attributes.
href | The server object handle reference. | |
att | The attribute identifier. | |
index | The index of the multivalued attribute. |
DC_RT_FMAC1 unsigned long dpws_get_int_att | ( | short | href, | |
int | att | |||
) |
Returns server object attributes of integer type (or boolean).
href | The server object handle reference. | |
att | The attribute identifier. |
DC_RT_FMAC1 int dpws_server_init | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | source | |||
) |
Initialize the dpws structure and perform server-side initialization.
The initialization includes:
[in,out] | dpws | A pointer on the main DPWS API runtime data structure. |
source | This structure will be useed in every SOAP message as the WSA source endpoint. The structure passed by the user will not be copied and must be kept allocated by the caller. |
DC_RT_FMAC1 int dpws_server_init_ex | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | source, | |||
int | listeners, | |||
int | bind_flags, | |||
int | backlog | |||
) |
Initialize the dpws structure and perform server-side initialization.
The initialization includes:
[in,out] | dpws | A pointer on the main DPWS API runtime data structure. |
source | This structure will be useed in every SOAP message as the WSA source endpoint. The structure passed by the user will not be copied and must be kept allocated by the caller. | |
listeners | Combination of DC_LISTENER_XXX flags to name listeners that will be started. | |
bind_flags | setsockopt flags to be applied to the TCP listening socket. | |
backlog | The connection backlog to use for TCP listeners. |
DC_RT_FMAC1 int dpws_accept | ( | struct dpws * | dpws | ) |
Blocks and wait for an incoming SOAP message or expired timer.
dpws | A pointer on the main DPWS API runtime data structure. When returning, this structure is initialized and ready to process the new request (using dpws_serve). |
Blocks and wait for an incoming SOAP message or expired timer.
This alternate version of dpws_accept is particularly suitable for multi-thread implementations since it makes performing the dpws_copy_context call unnecessary.
dpws | A pointer on the main DPWS API runtime data structure. When returning, this structure is not altered. | |
dpws_thr | A pointer on the service thread target DPWS API runtime data structure. When returning, this structure is initialized and ready to process the new request (using dpws_serve). The content of the structure is undefined if an error occured. |
DC_RT_FMAC1 int dpws_serve | ( | struct dpws * | dpws | ) |
Handles a request message.
This function starts reading the SOAP envelope, the SOAP headers and the SOAP body start tag before delegating further processing to the message handling function passed by a previous call to the server configuration functions.
DC_RT_FMAC1 int dpws_stop_server | ( | long | delay_ms | ) |
Stops smoothly the locally running server for multi-thread servers.
This function schedules the Eventing end notifications and Bye WS-Discovery messages for all the active devices, unblocks the main loop blocking on dpws_accept() and closes all open listening sockets. This functions blocks first until the scheduled messages are all being processed by server threads and lets an additional amount of time to let the server threads to send the messages. The dpws_stop_server_no_wait() function should be preferred if the developper can supply thread synchronization to avoid server threads to be stopped before having performed their tasks or in mono-thread servers where the call is performed in the server thread. A new call to dpws_server_init() must be then performed to restart the server.
delay_ms | the number of milliseconds to wait after the last "bye" task has been passed to a server thread and that must allow the thread to send pending messages. Must be tuned, especially if the number of threads is high. This is why one should use dpws_stop_server_no_wait() whenever possible. |
DC_RT_FMAC1 int dpws_stop_server_no_wait | ( | ) |
Stops smoothly the locally running server.
This function schedules the Eventing end notifications and Bye WS-Discovery messages for all the active devices, unblocks the main loop blocking on dpws_accept( and closes all open listening sockets. This functions returns immediately so either the developper can supply thread synchronization to avoid server threads to be stopped before having performed their tasks or use it in mono-thread servers. A new call to dpws_server_init() must be then performed to restart the server.
DC_RT_FMAC1 int dpws_join_network | ( | unsigned long | boot_seq | ) |
This API must be called after the network has been stopped (unplugged cable for instance) while the DPWS server was running to send hello messages for enabled devices.
Note that if network configuration changed, this API is not enough. The stack must be restarted (dpws_shutdown and dpws_init must be called).
boot_seq | A new boot number that must be supplied by the caller. It should be strictly superior to the current value. |
DC_RT_FMAC1 void* dpws_get_endpoint_user_data | ( | struct dpws * | dpws | ) |
Retrieves the user data associated to the endpoint that received the message.
dpws | A pointer on the main DPWS API runtime data structure. |
DC_RT_FMAC1 void* dpws_get_device_user_data | ( | struct dpws * | dpws | ) |
Retrieves the user data associated to the device instance that received the message.
dpws | A pointer on the main DPWS API runtime data structure. |
DC_RT_FMAC1 void* dpws_get_service_class_user_data | ( | struct dpws * | dpws | ) |
Retrieves the user data associated to the service class of the endpoint that received the message.
dpws | A pointer on the main DPWS API runtime data structure. |
DC_RT_FMAC1 void* dpws_malloc | ( | struct dpws * | dpws, | |
size_t | size | |||
) |
Allocate message transient memory.
This function is generally used in service implementations to allocate data structures for response messages.
DC_RT_FMAC1 int dpws_fault | ( | struct dpws * | dpws, | |
fault_value_t | value, | |||
const char * | faultstring, | |||
const char * | subcode, | |||
const char * | detail | |||
) |
Prepares a SOAP 1.2 fault.
To be called in a service function when the service invocation fails.
dpws | A pointer on the service dpws data structure. | |
value | The origin of the fault. | |
faultstring | SOAP 1.2 fault reason. | |
subcode | Optional SOAP 1.2 fault subcode. Potentially NULL. | |
detail | Optional SOAP 1.2 fault detail. Potentially NULL. |
DC_RT_FMAC1 int dpws_server_shutdown | ( | struct dpws * | dpws | ) |
Resets server configuration.
Should be called after the listener has been stopped using dpws_stop_server_XXX to clean the toolkit registry.
dpws | A optional (nullable) pointer on the main DPWS API runtime data structure. Kept for backwards compatibility. |
DC_RT_FMAC1 int dpws_client_init | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | source | |||
) |
Initialize the dpws structure and perform one-time client-side initialisation.
Must be called once before using a dpws structure.
[in,out] | dpws | A pointer on a DPWS API runtime data structure. |
source | This optional (nullable) structure will be used in every SOAP message as the WSA source endpoint. The structure passed by the user will not be copied and must be kept allocated by the caller. |
DC_RT_FMAC1 short* dpws_lookup | ( | struct dpws * | dpws, | |
char * | ns, | |||
char * | type, | |||
char * | scope, | |||
int * | res_size | |||
) |
Retrieves one or several device proxies basing on a type and a scope.
This function will first look for proxies into the local cache, and then generate a WS-Discovery Probe message if the number of requested proxies is not available in the cache. This function implements the semantics of the WS-Discovery Probe message, for a single device type. Note that this API uses a timeout which value is fixed according to WS-Discovery protocol metrics used by the DPWS specification and guarantees that all devices on the local network should have time to reply (currently 2600 ms). To specify a custom value, use the dpws_lookup_ex API.
dpws | A pointer on a dpws runtime data structure used to process the request. | |
ns | The target namespace of the device type. May be NULL only if the next parameter (type) is also NULL. | |
type | The local name of the device type. May be null, in which case no filtering on type is performed. | |
scope | An URI specifying the scope of the search. May be NULL, in which case the scope is unconstrained. The matching rule used for scope is the default one (RFC2396). | |
[in,out] | res_size | The maximum number of proxies to retrieve. When the function returns, it contains the actual number of retrieved device proxies. WARNING : if 0 or less is supplied, the number of devices to be retrieved is not constrained. |
DC_RT_FMAC1 short* dpws_lookup_ex | ( | struct dpws * | dpws, | |
discovery_filter_t * | filter, | |||
int | f_size, | |||
int * | res_size, | |||
unsigned int | time_out, | |||
cache_mode_t | mode | |||
) |
Retrieves one or several device endpoints basing on types and scopes.
This function implements the semantics of the WS-Discovery Probe message but providing the highest level of control. Furthermore several probe messages can be triggered according to the filter specified.
dpws | A pointer on a dpws runtime data structure used to process the request. | |
filter | The WS-Discovery filter array used for probe matches. Each individual filter has the "intersection" semantic (AND) but specifying several filters allows the caller to add a "union" semantic (OR) to the protocol by performing several consecutive probe operations. If NULL is provided, no filtering is performed at all. | |
f_size | The number of filters provided in the filter parameter. | |
[in,out] | res_size | The maximum number of proxies to retrieve. When the function returns, it contains the actual number of retrieved device endpoints. WARNING : if 0 or less is supplied, the number of devices to be retrieved is not constrained which could lead to memory exhaustion. |
time_out | A timeout in milliseconds after which the search should return, when the maximum number of requested proxies has not been reached. This must be a positive value. Note that this parameter is bounded by the DPWS constant MATCH_TIMEOUT which is 10 seconds. | |
mode | A specification on how the API should use the local cache. |
DC_RT_FMAC1 short dpws_lookup_by_id | ( | struct dpws * | dpws, | |
const char * | uuid | |||
) |
Checks a DPWS device is available on the local network and retrieve its proxy.
This function will first look for a device proxy into the local cache, and then generate a WS-Discovery Resolve message if the requested endpoint is not available in the cache. This function implements the semantics of the WS-Discovery Resolve message. Note that this API uses a timeout which value is the WSD_MATCH_TIMEOUT constant (currently 2600 ms).
dpws | A pointer on a dpws runtime data structure used to process the request. | |
uuid | The device logical ID. |
DC_RT_FMAC1 short dpws_probe_address | ( | struct dpws * | dpws, | |
char * | address, | |||
char * | ns, | |||
char * | type, | |||
char * | scope | |||
) |
Retrieves a device proxy checking a physical address matches a type and a scope.
This function issues a directed WS-Discovery Probe message to the supplied physical address and implements the semantics of this message.
dpws | A pointer on a dpws runtime data structure used to process the request. | |
address | The physical address to which the directed probe is sent. | |
ns | The target namespace of the type, as defined in the WSDL document. May be NULL only if the next parameter (type) is also NULL. | |
type | The local name of the device type. May be null, in which case no filtering on type is performed. | |
scope | An URI specifying the scope of the search. May be NULL, in which case the scope is unconstrained. The matching rule used for scope is the default one (RFC2396). |
DC_RT_FMAC1 short dpws_probe_address_ex | ( | struct dpws * | dpws, | |
char * | address, | |||
discovery_filter_t * | filter | |||
) |
Retrieves a device endpoint checking a physical address matches a set of types and scopes.
This function issues a directed WS-Discovery Probe message to the supplied physical address and implements the semantics of this message.
dpws | A pointer on a dpws runtime data structure used to process the request. | |
address | The physical address to which the directed probe is sent. | |
filter | The WS-Discovery filter used for probe match. Mandatory even if content is empty (no scope, no type). |
DC_RT_FMAC1 short* dpws_get_services | ( | struct dpws * | dpws, | |
short | href_device, | |||
char * | ns, | |||
char * | port_type, | |||
int * | res_size | |||
) |
Retrieve one or several service proxies basing on a device endpoint and a type.
This function will look for endpoints into the local cache or generate a WS-MetadataExchange GetMetadata message if necessary.
dpws | A pointer on a dpws runtime data structure used to process the request. | |
href_device | A valid device proxy handle reference that may have been retrieved using dpws_lookup. | |
ns | The target namespace of the port type, as defined in the WSDL document. | |
port_type | The name of the port type. May be null, in which case no filtering on type is performed. | |
[out] | res_size | The number of service proxies retrieved. |
DC_RT_FMAC1 short dpws_get_service_by_id | ( | struct dpws * | dpws, | |
short | href_device, | |||
char * | id | |||
) |
Retrieve a service proxy based on its service ID.
This function will first look for the service into the local cache, and then generate a WS-MetadataExchange GetMetadata message if the requested service is not available in the cache. This function implements the semantics of the WS-MetadataExchange GetMetadata message.
dpws | A pointer on a dpws runtime data structure used to process the request. | |
href_device | A valid device proxy handle reference that may have been retrieved using dpws_lookup. | |
id | The service ID. |
DC_RT_FMAC1 int dpws_pin_proxy | ( | short | href_proxy | ) |
Increase the use counter of a cached device or service so that is cannot be freed by the toolkit even if invalid from the cache point of view.
When the proxy is not used anymore, the user should use dpws_release_proxy to let it be freed.
href_proxy | The proxy handle reference to be pin. |
DC_RT_FMAC1 int dpws_release_proxy | ( | short | href_proxy | ) |
Decrease the use counter of a cached device or service so that it can be freed by the toolkit if invalid from the cache point of view.
href_proxy | The proxy handle reference to be released. |
DC_RT_FMAC1 proxy_type_t dpws_get_proxy_type | ( | short | href_proxy | ) |
Return the type of proxy returned by the dpws_get_services.
This API is useful to set if dpws_get_device_metadata or dpws_get_service_metadata must be used to retrieve proxy metadata.
href_proxy | The service proxy handle reference (a device is also a service). |
DC_RT_FMAC1 short dpws_get_proxy_by_id | ( | char * | id | ) |
Retrieves a cached proxy handle reference basing on an id.
For device proxies, the id considered is the device UUID. For service proxies, the service ID is defined by the DPWS specifications.
id | the proxy id to be searched. |
DC_RT_FMAC1 short dpws_get_proxy_by_address | ( | char * | address | ) |
Retrieves a cached proxy handle reference based on a physical address.
address | the proxy physical address to be searched. |
DC_RT_FMAC1 DC_BOOL dpws_check_proxy | ( | short | href_proxy | ) |
Check if a cached device or service is still valid from the cache point of view.
href_proxy | The proxy handle reference to be checked. |
DC_RT_FMAC1 int dpws_invalidate_proxy | ( | short | href | ) |
Removes a device or service proxy from the cache.
This function should be used when a call to a service using a given endpoint is unsuccessful because the endpoint cannot be reached. Note that even if the proxy status is changed and if it is removed from the cache, the proxy object remains (or should remain) hold by the caller that may release it using dpws_release_proxy for memory retrieval.
href | The device or hosted service proxy href. |
DC_RT_FMAC1 DC_BOOL dpws_device_proxy_match | ( | short | href_device, | |
discovery_filter_t * | criterion | |||
) |
Checks a device matches a given WS-Discovery match criterion.
This function may be used when a discovery callback has been triggered.
href_device | The device proxy handle reference. | |
criterion | a WS-Discovery filter as used for probe match. Mandatory even if content is empty (no scope, no type). |
DC_RT_FMAC1 unsigned long dpws_cache_get_device_metadata_version | ( | short | href_device | ) |
Retrieves the metadata version of a cached device proxy.
href_device | The device proxy. |
DC_RT_FMAC1 char** dpws_cache_get_scopes | ( | struct dpws * | dpws, | |
short | href_device | |||
) |
Retrieves the scopes of a device in the cache.
dpws | A pointer on a dpws data structure used to process the API call. | |
href_device | A valid device proxy handle reference that may have been retrieved using dpws_lookup. |
DC_RT_FMAC1 char* dpws_cache_get_uuid | ( | struct dpws * | dpws, | |
short | href_device | |||
) |
Retrieves the uuid of a device in the cache.
dpws | A pointer on a dpws data structure used to process the API call or NULL if the result must be allocated on the heap and should be freed using dpws_free(). | |
href_device | A valid device proxy handle reference that may have been retrieved using dpws_lookup. |
DC_RT_FMAC1 char** dpws_cache_get_device_transport_addresses | ( | struct dpws * | dpws, | |
short | href_device, | |||
int * | res_size | |||
) |
Retrieves in the cache the URLs for a device.
dpws | A pointer on a dpws data structure used to allocate the result. | |
href_device | The device proxy handle reference. | |
[out] | res_size | The number of URLs retrieved. |
DC_RT_FMAC1 struct wsa_endpoint_ref* dpws_get_default_endpoint_ref | ( | struct dpws * | dpws, | |
short | href_proxy | |||
) | [read] |
Gets the default endpoint reference for a device or service proxy.
In this version, the first endpoint is considered. If a specific endpoint reference is required, use the dpws_get_endpoint_refs.
dpws | A pointer on a dpws data structure used to allocate the result. If NULL, the result is allocated on the process heap. | |
href_proxy | The device or service proxy which endpoint reference must be retrieved for. |
DC_RT_FMAC1 struct wsa_endpoint_ref** dpws_get_endpoint_refs | ( | struct dpws * | dpws, | |
short | href_proxy, | |||
int * | res_size | |||
) | [read] |
Gets all the endpoint references retrieved for a device or service proxy.
dpws | A pointer on a dpws data structure used to allocate the result. If NULL, the result is allocated on the process heap. | |
href_proxy | The device or service proxy which endpoint references must be retrieved for. | |
[out] | res_size | The number of endpoints retrieved. |
DC_RT_FMAC1 struct device_metadata* dpws_get_device_metadata | ( | struct dpws * | dpws, | |
short | href_device | |||
) | [read] |
Retrieves the whole DPWS metadata for a device.
This API uses the WS-Transfer Get request and the WS-MetadataExchange message format. This API, like all the functions WS-Metadata Exchange APIs, does not cache the results of network queries performed so that a query is performed every time.
dpws | A pointer on a dpws data structure used to process the request. | |
href_device | The device proxy handle reference that may have been retrieved using dpws_lookup. |
DC_RT_FMAC1 struct service_metadata* dpws_get_service_metadata | ( | struct dpws * | dpws, | |
short | href_service | |||
) | [read] |
Retrieves the service DPWS metadata for a hosted service.
This function uses no dialect in the GetMetadata request. This API, like all the functions WS-Metadata Exchange APIs, does not cache the results of network queries performed so that a query is performed every time.
dpws | A pointer on a dpws data structure used to process the request. | |
href_service | A hosted service proxy handle reference. |
DC_RT_FMAC1 short dpws_get_host_device_proxy | ( | short | href_service | ) |
Retrieves in the cache the hosting device proxy of a hosted service.
This function only uses the cache.
href_service | A hosted service proxy handle reference. |
DC_RT_FMAC1 struct wsa_endpoint_ref* dpws_event_subscribe | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | event_source, | |||
struct wsa_endpoint_ref * | notify_to, | |||
struct wsa_endpoint_ref * | end_to, | |||
char ** | filter, | |||
char ** | expiration | |||
) | [read] |
Subscribes to a WS-Eventing event source.
This version of the API is supposed to be used:
dpws | A pointer on a dpws data structure used to process the request. | |
event_source | A valid endpoint reference (that may have been retrieved using dpws_lookup or dpws_get_services) of an WS-Eventing event source. | |
notify_to | A valid device endpoint reference (that may have been retrieved using dpws_lookup) that will receive the events. | |
end_to | A valid device endpoint reference (that may have been retrieved using dpws_lookup) that will receive abnormal subscription termination. Optional (if NULL no termination event is sent). | |
filter | A NULL-terminated string array of DPWS actions to limit events to receive from the event source. | |
[in,out] | expiration | An XML Schema dateTime or duration, to specify the subscription duration requested. This parameter will be modified with the value granted by the subscription manager with a string allocated on the dpws runtime allocator. If no expiration is provided, a default value will be provided by the device. |
DC_RT_FMAC1 struct wsa_endpoint_ref* dpws_event_subscribe_ex | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | event_source, | |||
short | href_notify_to, | |||
short | href_end_to, | |||
char ** | filter, | |||
char ** | expiration | |||
) | [read] |
Subscribes to a WS-Eventing event source for a local event sink.
This version of the API is supposed to be used when the notify_to & end_to are local service ports (i.e. network endpoints) and performs automatic EPR selection.
dpws | A pointer on a dpws data structure used to process the request. | |
event_source | A valid endpoint (that may have been retrieved using dpws_lookup or dpws_get_services) of an WS-Eventing event source. | |
href_notify_to | The handle of a local service port that will receive the events. | |
href_end_to | The handle of a local service port that will receive abnormal subscription termination. Optional (if -1 no termination event is sent). | |
filter | A NULL-terminated string array of DPWS actions to limit events to receive from the event source. | |
[in,out] | expiration | An XML Schema dateTime or duration, to specify the subscription duration requested. This parameter will be modified with the value granted by the subscription manager with a string allocated on the dpws runtime allocator. If no expiration is provided, a default value will be provided by the device. |
DC_RT_FMAC1 char* dpws_event_renew | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | subscription_manager, | |||
char * | expiration | |||
) |
Renews a subscription to a WS-Eventing event source.
dpws | A pointer on a dpws data structure used to process the request. | |
subscription_manager | The subscription ticket gained during initial call to dpws_event_subscribe. | |
expiration | XML Schema dateTime or duration, to specify the new subscription duration requested. If NULL is provided, the renew duration is provided by the device. |
DC_RT_FMAC1 char* dpws_event_status | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | subscription_manager | |||
) |
Gets the remaining duration for a subscription to a WS-Eventing event source.
dpws | A pointer on a dpws data structure used to process the request. | |
subscription_manager | The subscription ticket gained during initial call to dpws_event_subscribe. |
DC_RT_FMAC1 int dpws_event_unsubscribe | ( | struct dpws * | dpws, | |
struct wsa_endpoint_ref * | subscription_manager | |||
) |
Cancel a running subscription to a WS-Eventing event source.
dpws | A pointer on a dpws data structure used to process the request. | |
subscription_manager | The subscription ticket gained during initial call to dpws_event_subscribe. |
DC_RT_FMAC1 int dpws_end | ( | struct dpws * | dpws | ) |
Clears structures and free dynamically allocated memory used for request processing.
Must be called after processing a message on a client, a server or a handler.
DC_RT_FMAC1 int dpws_get_error | ( | struct dpws * | dpws | ) |
DC_RT_FMAC1 const char* dpws_get_error_msg | ( | struct dpws * | dpws | ) |
DC_RT_FMAC1 void dpws_default_wsa_endpoint_ref | ( | struct wsa_endpoint_ref * | endpoint_ref | ) |
Initialize a wsa_endpoint_ref structure that the user may use for a subsequent API call.
endpoint_ref | his structure will be reset. |
DC_RT_FMAC1 struct wsa_endpoint_ref* dpws_create_device_endpoint_ref | ( | char * | uuid | ) | [read] |
Allocates and initialize a wsa_endpoint_ref structure for a device.
No verification is performed for device existence (this could be done thanks to the dpws_lookup_by_id API).
uuid | A device uuid. |
DC_RT_FMAC1 struct wsa_endpoint_ref* dpws_endpoint_ref_dup | ( | struct wsa_endpoint_ref * | endpoint | ) | [read] |
Creates a deep copy of a wsa_endpoint_ref structure on DPWS library heap.
May be used for instance to keep a WS-Eventing subscription endpoint after dpws_end has been called.
endpoint | The structure to copy. |
DC_RT_FMAC1 struct wsa_endpoint_ref* dpws_endpoint_ref_copy | ( | struct wsa_endpoint_ref * | dest, | |
struct wsa_endpoint_ref * | src | |||
) | [read] |
Copy of a wsa_endpoint_ref structure to a provided destination.
This function uses the standard malloc function to allocate the structure contents.
dest | he destination structure. | |
src | The structure to copy. |
DC_RT_FMAC1 void dpws_free | ( | void * | buffer | ) |
Frees a string or any buffer allocated on the DPWS library heap.
buffer | The memory block to be freed. |
DC_RT_FMAC1 void dpws_endpoint_ref_content_free | ( | struct wsa_endpoint_ref * | endpoint | ) |
Frees the contents of an endpoint reference.
Liberates the contents of a wsa_endpoint_ref structure allocated on the DPWS library heap. This function can be used along with dpws_endpoint_ref_copy.
endpoint | The structure which contents must be freed. |
DC_RT_FMAC1 void dpws_endpoint_ref_free | ( | struct wsa_endpoint_ref * | endpoint | ) |
Frees an endpoint reference and its contents.
This function can be used along with dpws_endpoint_ref_dup.
endpoint | The structure which must be freed. |
DC_RT_FMAC1 void dpws_endpoint_ref_array_free | ( | struct wsa_endpoint_ref ** | endpoints, | |
int | nb_endpoints | |||
) |
Frees an endpoint reference array and its contents.
This function can be used along with dpws_endpoint_ref_dup that allows for instance the user to keep the selected endpoint reference before array deletion.
endpoints | A array of endpoint reference pointers. | |
nb_endpoints | The size of the array to free. |