C:/sr/Dev/Schneider/dpws_2_0M11fix/dpws/src/dpws.h File Reference

#include "stdsoap2.h"

Data Structures

struct  wsa_endpoint_ref
 WS-Adressing endpoint reference Runtime structure that contains WS-addressing endpoint reference data. More...
struct  dpws
 DPWS toolkit runtime structure Main DPWS API runtime data structure. More...
struct  qname
 An XML qualified name used for instance for WS-Discovery port types. More...
struct  prefixed_qname
 An XML qualified name with a prefix specification used for instance for WS-Discovery port types. More...
struct  model_info
 Container for WS-MedataExchange APIs results. More...
struct  device_info
 Container for WS-MedataExchange APIs results. More...
struct  wsdl_info
 Container for WS-MedataExchange APIs results. More...
struct  service_info
 Container for WS-MedataExchange APIs results. More...
struct  device_metadata
 Container for WS-MedataExchange APIs results. More...
struct  service_metadata
 Container for WS-MedataExchange APIs results. More...
struct  event_end_info
 Container for WS-Eventing subscription end event. More...
struct  localized_string
 Used for API parameters that are localized using the xml:lang attribute. More...

Defines

#define DPWS_OK   SOAP_OK
 DPWS API error codes.
#define dpws_dpws2soap(dpws)   (&dpws->soap)
 Macro for transforming a DPWS runtime structure into a gSOAP runtime structure.
#define dpws_soap2dpws(soap)   ((struct dpws*)(soap))
 Macro for transforming a gSOAP runtime structure into a DPWS runtime structure (provided the gSOAP structure is in fact embedded in a DPWS structure).

Functions

SOAP_FMAC1 int SOAP_FMAC2 dpws_init ()
 DPWS tookit initialization function.
SOAP_FMAC1 int SOAP_FMAC2 dpws_shutdown ()
 Shutdowns the DPWS toolkit.
SOAP_FMAC1 short SOAP_FMAC2 dpws_create_device_class ()
 Creates an empty device class object.
SOAP_FMAC1 short SOAP_FMAC2 dpws_create_service_class ()
 Creates an empty service class object.
SOAP_FMAC1 int SOAP_FMAC2 dpws_register_service_class (short device_class_href, short service_class_href)
 Associates a service class to a device class.
SOAP_FMAC1 short SOAP_FMAC2 dpws_create_device (unsigned short local_id, short class_href)
 Creates a device instance object with all associated hosted services in one API call.
SOAP_FMAC1 short SOAP_FMAC2 dpws_create_custom_device (unsigned short local_id, short class_href)
 Creates a device instance object without hosted services.
SOAP_FMAC1 short SOAP_FMAC2 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.
SOAP_FMAC1 short SOAP_FMAC2 dpws_create_service_port ()
 Creates a new service port on the default HTTP listener.
SOAP_FMAC1 int SOAP_FMAC2 dpws_bind_service (short hrefService, short hrefServicePort)
 Publishes a service endpoint on a specific address (service port).
SOAP_FMAC1 short SOAP_FMAC2 dpws_create_endpoint ()
 Creates an endpoint and a bound service port.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_device_class_handle (char *id)
 Retrieves a device class handle by its id attribute.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_service_class_handle (char *id)
 Retrieves a service class handle by its id attribute.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_device_handle (char *uuid)
 Retrieves a device handle by its uuid.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_service_handle (short device_href, char *service_id)
 Retrieves a hosted service handle by its service identifier.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_service_handle_by_class (short device_href, short service_class_href)
 Retrieves a hosted service handle by its service class.
SOAP_FMAC1 int SOAP_FMAC2 dpws_get_service_handles (short device_href, short *hrefs, int *len)
 Retrieves service handles attached to a device instance.
SOAP_FMAC1 int SOAP_FMAC2 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.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_default_service_port (short endpoint_href)
 Get the default service port handle reference bound to a device or service endpoint.
SOAP_FMAC1 struct wsa_endpoint_ref
*SOAP_FMAC2 
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.
SOAP_FMAC1 char *SOAP_FMAC2 dpws_get_transport_address (short href_service_port)
 Builds the physical address for a local service port.
SOAP_FMAC1 int SOAP_FMAC2 dpws_delete_hosted_service (short service_href)
 Deletes a hosted service.
SOAP_FMAC1 int SOAP_FMAC2 dpws_update_metadata (short device_href)
 DPWS metadata change commit function.
SOAP_FMAC1 int SOAP_FMAC2 dpws_enable_device (short device_href)
 Make a device available on the network.
SOAP_FMAC1 int SOAP_FMAC2 dpws_disable_device (short device_href)
 Removes a device from the network.
SOAP_FMAC1 int SOAP_FMAC2 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).
SOAP_FMAC1 int SOAP_FMAC2 dpws_set_int_att (short href, int att, unsigned long value)
 Used to set a server object attribute value for integer types (boolean included).
SOAP_FMAC1 int SOAP_FMAC2 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.
SOAP_FMAC1 int SOAP_FMAC2 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.
SOAP_FMAC1 void *SOAP_FMAC2 dpws_get_ptr_att (short href, int att)
 Returns server object attributes for pointer types (string or not) attributes.
SOAP_FMAC1 void *SOAP_FMAC2 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.
SOAP_FMAC1 unsigned long SOAP_FMAC2 dpws_get_int_att (short href, int att)
 Returns server object attributes of integer type (or boolean).
SOAP_FMAC1 int SOAP_FMAC2 dpws_release_handle (short href)
 Releases a toolkit configuration object handle when not needed anymore by the user.
SOAP_FMAC1 int SOAP_FMAC2 dpws_server_init (struct dpws *dpws, struct wsa_endpoint_ref *source)
 Initialize the dpws structure and perform server-side initialization.
SOAP_FMAC1 int SOAP_FMAC2 dpws_accept (struct dpws *dpws)
 Blocks and wait for an incoming SOAP message.
SOAP_FMAC1 int SOAP_FMAC2 dpws_accept_thr (struct dpws *dpws, struct dpws *dpws_thr)
 Blocks and wait for an incoming SOAP message.
SOAP_FMAC1 int SOAP_FMAC2 dpws_serve (struct dpws *dpws)
 Handles a request message.
SOAP_FMAC1 int SOAP_FMAC2 dpws_stop_server (long delay_ms)
 Stops smoothly the locally running server for multi-thread servers.
SOAP_FMAC1 int SOAP_FMAC2 dpws_stop_server_no_wait ()
 Stops smoothly the locally running server.
SOAP_FMAC1 void *SOAP_FMAC2 dpws_get_endpoint_user_data (struct dpws *dpws)
 Retrieves the user data associated to the endpoint that received the message.
SOAP_FMAC1 void *SOAP_FMAC2 dpws_get_device_user_data (struct dpws *dpws)
 Retrieves the user data associated to the device instance that received the message.
SOAP_FMAC1 int SOAP_FMAC2 dpws_end (struct dpws *dpws)
 Clears structures and free dynamically allocated memory used for request processing.
SOAP_FMAC1 int SOAP_FMAC2 dpws_client_init (struct dpws *dpws, struct wsa_endpoint_ref *source)
 Initialize the dpws structure and perform one-time client-side initialisation.
SOAP_FMAC1 short *SOAP_FMAC2 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.
SOAP_FMAC1 short *SOAP_FMAC2 dpws_lookup_ex (struct dpws *dpws, struct qname *types, char **scopes, int match_rule, int *res_size, long time_out, int mode)
 Retrieves one or several device endpoints basing on types and scopes.
SOAP_FMAC1 short SOAP_FMAC2 dpws_lookup_by_id (struct dpws *dpws, char *uuid)
 Checks a DPWS device is available on the local network and retrieve its proxy.
SOAP_FMAC1 short SOAP_FMAC2 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.
SOAP_FMAC1 short SOAP_FMAC2 dpws_probe_address_ex (struct dpws *dpws, char *address, struct qname *types, char **scopes, int match_rule)
 Retrieves a device endpoint checking a physical address matches a set of types and scopes.
SOAP_FMAC1 short *SOAP_FMAC2 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.
SOAP_FMAC1 proxy_type SOAP_FMAC2 dpws_get_proxy_type (short href_proxy)
 Return the type of proxy returned by the dpws_get_services.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_service_by_id (struct dpws *dpws, short href_device, char *id)
 Retrieve a service proxy based on its service ID.
SOAP_FMAC1 char **SOAP_FMAC2 dpws_cache_get_scopes (struct dpws *dpws, short href_device)
 Retrieves the scopes of a device in the cache.
SOAP_FMAC1 char *SOAP_FMAC2 dpws_cache_get_uuid (struct dpws *dpws, short href_device)
 Retrieves the uuid of a device in the cache.
SOAP_FMAC1 int SOAP_FMAC2 dpws_check_device_type (struct dpws *dpws, char *ns, char *type, int match_rule, short href_device)
 Checks a device is of a given type.
SOAP_FMAC1 struct qname
**SOAP_FMAC2 
dpws_cache_get_types (struct dpws *dpws, short href_proxy)
 Retrieves the port types for a device or service proxy lying in the cache.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_proxy_by_id (char *id)
 Retrieves a cached proxy handle reference basing on an id.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_proxy_by_address (char *address)
 Retrieves a cached proxy handle reference basing on a physical address.
SOAP_FMAC1 BOOLEAN SOAP_FMAC2 dpws_check_proxy (short href_proxy)
 Check if a cached device or service is still valid from the cache point of view.
SOAP_FMAC1 int SOAP_FMAC2 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.
SOAP_FMAC1 int SOAP_FMAC2 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.
SOAP_FMAC1 struct wsa_endpoint_ref
*SOAP_FMAC2 
dpws_get_default_endpoint_ref (struct dpws *dpws, short href_proxy)
 Gets the default endpoint reference for a device or service proxy.
SOAP_FMAC1 struct wsa_endpoint_ref
**SOAP_FMAC2 
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.
SOAP_FMAC1 unsigned long SOAP_FMAC2 dpws_cache_get_device_metadata_version (short href_device)
 Retrieves the metadata version of a cached device proxy.
SOAP_FMAC1 char **SOAP_FMAC2 dpws_cache_get_device_transport_addresses (struct dpws *dpws, short href_device, int *res_size)
 Retrieves in the cache the URLs for a device.
SOAP_FMAC1 int SOAP_FMAC2 dpws_invalidate_proxy (short href)
 Remove a device or service proxy from the cache.
SOAP_FMAC1 struct device_metadata
*SOAP_FMAC2 
dpws_get_device_metadata (struct dpws *dpws, short href_device)
 Retrieves the whole DPWS metadata for a device.
SOAP_FMAC1 struct service_metadata
*SOAP_FMAC2 
dpws_get_service_metadata (struct dpws *dpws, short href_service)
 Retrieves the service DPWS metadata for a hosted service.
SOAP_FMAC1 short SOAP_FMAC2 dpws_get_host_device_proxy (short href_service)
 Retrieves in the cache the hosting device proxy of a hosted service.
SOAP_FMAC1 struct wsa_endpoint_ref
*SOAP_FMAC2 
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.
SOAP_FMAC1 char *SOAP_FMAC2 dpws_event_renew (struct dpws *dpws, struct wsa_endpoint_ref *subscription_manager, char *expiration)
 Renews a subscription to a WS-Eventing event source.
SOAP_FMAC1 char *SOAP_FMAC2 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.
SOAP_FMAC1 int SOAP_FMAC2 dpws_event_unsubscribe (struct dpws *dpws, struct wsa_endpoint_ref *subscription_manager)
 Cancel a running subscription to a WS-Eventing event source.
SOAP_FMAC1 char **SOAP_FMAC2 dpws_set_device_scopes (struct dpws *dpws, short href_device, char **scopes)
 Changes a remote device scope that exposes the MDM service.
SOAP_FMAC1 struct localized_string
**SOAP_FMAC2 
dpws_set_device_friendly_names (struct dpws *dpws, short href_device, struct localized_string **names)
 Changes a remote device friendly name that exposes the MDM service.
SOAP_FMAC1 int SOAP_FMAC2 dpws_recv_empty_response (struct dpws *dpws)
 Receives one way or asynchronous empty response.
SOAP_FMAC1 int SOAP_FMAC2 dpws_get_error (struct dpws *dpws)
 Returns the last DPWS or gSOAP runtime error.
SOAP_FMAC1 const char *SOAP_FMAC2 dpws_get_error_msg (struct dpws *dpws)
 Gets a message for a SOAP fault or a DPWS/gSOAP error that has previously occurred.
SOAP_FMAC1 void SOAP_FMAC2 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.
SOAP_FMAC1 struct wsa_endpoint_ref
*SOAP_FMAC2 
dpws_create_device_endpoint_ref (char *uuid)
 Allocates and initialize a wsa_endpoint_ref structure for a device.
SOAP_FMAC1 struct wsa_endpoint_ref
*SOAP_FMAC2 
dpws_endpoint_ref_dup (struct wsa_endpoint_ref *endpoint)
 Creates a deep copy of a wsa_endpoint_ref structure on DPWS library heap.
SOAP_FMAC1 struct wsa_endpoint_ref
*SOAP_FMAC2 
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.
SOAP_FMAC1 void SOAP_FMAC2 dpws_free (void *buffer)
 Frees a string or any buffer allocated on the DPWS library heap.
SOAP_FMAC1 void SOAP_FMAC2 dpws_endpoint_ref_content_free (struct wsa_endpoint_ref *endpoint)
 Frees the contents of an endpoint reference.
SOAP_FMAC1 void SOAP_FMAC2 dpws_endpoint_ref_free (struct wsa_endpoint_ref *endpoint)
 Frees an endpoint reference and its contents.
SOAP_FMAC1 void SOAP_FMAC2 dpws_endpoint_ref_array_free (struct wsa_endpoint_ref **endpoints, int nb_endpoints)
 Frees an endpoint reference array and its contents.
SOAP_FMAC1 time_t SOAP_FMAC2 get_system_time ()
 Retrieves the system time in an UNIX-like date format.
SOAP_FMAC1 time_t SOAP_FMAC2 xmlduration2time (char *xml_duration)
 Converts an XML Schema duration value into an UNIX-like date.
SOAP_FMAC1 char *SOAP_FMAC2 time2xmlduration (char *dest, time_t time)
 Converts an UNIX-like date into an XML Schema duration value.
SOAP_FMAC1 int SOAP_FMAC2 dpws_strcasecmp (const char *s1, const char *s2)
 A portable version of a case-insensitive strcmp.

Detailed Description

DPWS Toolkit API Reference.

Define Documentation

#define dpws_dpws2soap ( dpws   )     (&dpws->soap)

Macro for transforming a DPWS runtime structure into a gSOAP runtime structure.

Parameters:
dpws a DPWS runtime structure

#define dpws_soap2dpws ( soap   )     ((struct dpws*)(soap))

Macro for transforming a gSOAP runtime structure into a DPWS runtime structure (provided the gSOAP structure is in fact embedded in a DPWS structure).

Parameters:
soap a gSOAP runtime structure


Function Documentation

SOAP_FMAC1 int SOAP_FMAC2 dpws_accept ( struct dpws dpws  ) 

Blocks and wait for an incoming SOAP message.

To be used in a server or handler context.

Parameters:
dpws A pointer on the main DPWS API runtime data structure. When returning this structure contains both the listening and the accepted sockets.
Returns:
DPWS_OK, if no error occurred. A DPWS or gSOAP error code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 dpws_accept_thr ( struct dpws dpws,
struct dpws dpws_thr 
)

Blocks and wait for an incoming SOAP message.

To be used in a server or handler context. This alternate version of dpws_accept is particularly suited to multi-thread implementations since it make unnecessary to perform the dpws_copy_contex call.

Parameters:
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 contains the accepted socket.
Returns:
DPWS_OK, if no error occurred. A DPWS or gSOAP error code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
href The server object handle reference.
att The attribute identifier.
value The integer parameter value.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
href The server object handle reference.
att The attribute identifier.
value The parameter value. Must be of the appropriate type, depending on the attribute.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 dpws_bind_service ( short  hrefService,
short  hrefServicePort 
)

Publishes a service endpoint on a specific address (service port).

Parameters:
hrefService The service endpoint handle reference.
hrefServicePort The service port handle reference.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 unsigned long SOAP_FMAC2 dpws_cache_get_device_metadata_version ( short  href_device  ) 

Retrieves the metadata version of a cached device proxy.

Parameters:
href_device The device proxy.
Returns:
The metadata version or a DPWS error code.

SOAP_FMAC1 char** SOAP_FMAC2 dpws_cache_get_device_transport_addresses ( struct dpws dpws,
short  href_device,
int *  res_size 
)

Retrieves in the cache the URLs for a device.

Parameters:
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.
Returns:
An array of strings containing the transport addresses of the device.

SOAP_FMAC1 char** SOAP_FMAC2 dpws_cache_get_scopes ( struct dpws dpws,
short  href_device 
)

Retrieves the scopes of a device in the cache.

Parameters:
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.
Returns:
a null-terminated array of strings featuring the scopes. Data is allocated on the dpws structure and will be freed during the next call to dpws_end. An empty result may result from an API error.

SOAP_FMAC1 struct qname** SOAP_FMAC2 dpws_cache_get_types ( struct dpws dpws,
short  href_proxy 
)

Retrieves the port types for a device or service proxy lying in the cache.

Parameters:
dpws A pointer on a dpws data structure used to process the API call.
href_proxy The device or hosted service proxy.
Returns:
a null-terminated array of pointers on qname structures featuring the port types. Data is allocated on the dpws structure and will be freed during the next call to dpws_end. An empty result may result from an API error.

SOAP_FMAC1 char* SOAP_FMAC2 dpws_cache_get_uuid ( struct dpws dpws,
short  href_device 
)

Retrieves the uuid of a device in the cache.

Parameters:
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.
Returns:
a string featuring the device uuid. Data is allocated on the dpws structure and will be freed during the next call to dpws_end. An empty result may result from an API error.

SOAP_FMAC1 int SOAP_FMAC2 dpws_check_device_type ( struct dpws dpws,
char *  ns,
char *  type,
int  match_rule,
short  href_device 
)

Checks a device is of a given type.

This function may be used when a discovery callback has been triggered.

Parameters:
dpws A pointer on a dpws runtime data structure.
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.
match_rule The matching rule to be used for scope comparison. Should be one of:
  • WSD_MATCH_BY_RFC2396,
  • WSD_MATCH_BY_UUID,

SOAP_FMAC1 BOOLEAN SOAP_FMAC2 dpws_check_proxy ( short  href_proxy  ) 

Check if a cached device or service is still valid from the cache point of view.

Parameters:
href_proxy The proxy handle reference to be checked.
Returns:
TRUE if the handle exist and is valid.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
[in,out] dpws A pointer on a DPWS API runtime data structure.
source This structure will be copied in every SOAP message as the WSA source endpoint. The structure passed by the user will be copied and can be released.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 short SOAP_FMAC2 dpws_create_custom_device ( unsigned short  local_id,
short  class_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.

Parameters:
local_id A numeric identifier for the device instance that, with the listening port and the MAC address, will be used to generate the device logical address (i.e., the uuid).
class_href The device class handle reference.
Returns:
A handle reference, if no error occurred. a negative error code otherwise.

SOAP_FMAC1 short SOAP_FMAC2 dpws_create_device ( unsigned short  local_id,
short  class_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 class of the device. Each service created will also have its own HTTP service port to which is will be bound.

Parameters:
local_id A numeric identifier for the device instance that, with the listening port and the MAC address, will be used to generate the device logical address (i.e., the uuid). Note that the 65535 value is reserved.
class_href The device class handle reference.
Returns:
A handle reference, if no error occurred. a negative error code otherwise.

SOAP_FMAC1 short SOAP_FMAC2 dpws_create_device_class (  ) 

Creates an empty device class object.

Returns:
A handle reference, if no error occurred. -1 otherwise.

SOAP_FMAC1 struct wsa_endpoint_ref* SOAP_FMAC2 dpws_create_device_endpoint_ref ( char *  uuid  ) 

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

Parameters:
uuid A device uuid.
Returns:
A DPWS library heap allocated endpoint reference. The caller is responsible for liberation when no more needed (using dpws_endpoint_ref_free).

SOAP_FMAC1 short SOAP_FMAC2 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

Returns:
A handle reference, if no error occurred. a negative error code otherwise.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
device_href The device instance handle reference.
service_class_href The service class handle reference.
Returns:
A handle reference, if no error occurred. a negative error code otherwise.

SOAP_FMAC1 short SOAP_FMAC2 dpws_create_service_class (  ) 

Creates an empty service class object.

Returns:
A handle reference, if no error occurred. -1 otherwise.

SOAP_FMAC1 short SOAP_FMAC2 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.

Returns:
A handle reference, if no error occurred. a negative error code otherwise.

SOAP_FMAC1 void SOAP_FMAC2 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.

Parameters:
endpoint_ref his structure will be reset.

SOAP_FMAC1 int SOAP_FMAC2 dpws_delete_hosted_service ( short  service_href  ) 

Deletes a hosted service.

Undeploys a hosted service. WARNING ! The current version DPWS does not really support "hot" configuration. This API was added for DPWS Interop Workshop (October 2005) purpose.

Parameters:
service_href The service handle reference.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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. WARNING ! The current version DPWS does not really support "hot" configuration.

Parameters:
device_href The device handle reference.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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. WARNING ! The current version DPWS does not really support "hot" configuration.

Parameters:
device_href The device handle reference.
Returns:
DPWS_OK, if no error occurred. A DPWS error code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
dpws A pointer on a dpws data structure that was used to process the request.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 void SOAP_FMAC2 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.

Parameters:
endpoints A array of endpoint reference pointers.
nb_endpoints The size of the array to free.

SOAP_FMAC1 void SOAP_FMAC2 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.

Parameters:
endpoint The structure which contents must be freed.

SOAP_FMAC1 struct wsa_endpoint_ref* SOAP_FMAC2 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.

This function uses the standard malloc function to allocate the structure contents.

Parameters:
dest he destination structure.
src The structure to copy.
Returns:
The dest param. The API user will have the responsibility to free the allocated contents of the structure using dpws_dpws_endpoint_ref_content_free.

SOAP_FMAC1 struct wsa_endpoint_ref* SOAP_FMAC2 dpws_endpoint_ref_dup ( struct wsa_endpoint_ref endpoint  ) 

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.

Parameters:
endpoint The structure to copy.
Returns:
A heap allocated endpoint reference. The caller is responsible for liberation when no more needed (using dpws_endpoint_ref_free).

SOAP_FMAC1 void SOAP_FMAC2 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.

Parameters:
endpoint The structure which must be freed.

SOAP_FMAC1 char* SOAP_FMAC2 dpws_event_renew ( struct dpws dpws,
struct wsa_endpoint_ref subscription_manager,
char *  expiration 
)

Renews a subscription to a WS-Eventing event source.

Parameters:
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.
Returns:
The subscription duration (XML Schema dateTime or duration) granted by the manager. NULL if an error occurred.

SOAP_FMAC1 char* SOAP_FMAC2 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.

Parameters:
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.
Returns:
The subscription duration (XML Schema dateTime or duration) still running. NULL if an error occurred.

SOAP_FMAC1 struct wsa_endpoint_ref* SOAP_FMAC2 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.

Parameters:
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.
notify_to A valid device endpoint (that may have been retrieved using dpws_lookup) that will receive the events.
end_to A valid device endpoint (that may have been retrieved using dpws_lookup) that will receive abnormal subscription termination. Optional (if NULL no termination event is not 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.
Returns:
The subscription manager endpoint that shall be used as a ticket to manage the subscription. NULL if an error occurred.

SOAP_FMAC1 int SOAP_FMAC2 dpws_event_unsubscribe ( struct dpws dpws,
struct wsa_endpoint_ref subscription_manager 
)

Cancel a running subscription to a WS-Eventing event source.

Parameters:
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.
Returns:
DPWS_OK, if no error occurred. A DPWS or gSOAP error code otherwise.

SOAP_FMAC1 void SOAP_FMAC2 dpws_free ( void *  buffer  ) 

Frees a string or any buffer allocated on the DPWS library heap.

Parameters:
buffer The memory block to be freed.

SOAP_FMAC1 struct wsa_endpoint_ref* SOAP_FMAC2 dpws_get_default_endpoint_ref ( struct dpws dpws,
short  href_proxy 
)

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.

Parameters:
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.
Returns:
An endpoint reference structure. Must be freed by the user using dpws_end if a dpws structure was provided, dpws_endpoint_ref_free else.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
endpoint_href The (service) endpoint handle reference.
Returns:
The handle reference of the default service port.

SOAP_FMAC1 short SOAP_FMAC2 dpws_get_device_class_handle ( char *  id  ) 

Retrieves a device class handle by its id attribute.

Parameters:
id The device class id attribute.
Returns:
A handle reference, if found. -1 otherwise.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
uuid the device uuid.
Returns:
the handle reference for the device if local. -1 else.

SOAP_FMAC1 struct device_metadata* SOAP_FMAC2 dpws_get_device_metadata ( struct dpws dpws,
short  href_device 
)

Retrieves the whole DPWS metadata for a device.

This API uses the WS-Transfer Get request and the WS-MetadataExchange message format. Like, does not cache the results of network queries performed so that a query is performed every time.

Parameters:
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.
Returns:
A structure containing metadata allocated on the dpws structure ( freed during the next call to dpws_end).

SOAP_FMAC1 void* SOAP_FMAC2 dpws_get_device_user_data ( struct dpws dpws  ) 

Retrieves the user data associated to the device instance that received the message.

Parameters:
dpws A pointer on the main DPWS API runtime data structure.
Returns:
A pointer on the data set on the device by the user.

SOAP_FMAC1 struct wsa_endpoint_ref** SOAP_FMAC2 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.

Parameters:
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.
Returns:
An array of endpoint references. The returned array and endpoint structures are dynamically allocated on the gSOAP or process heap. This data must be freed using dpws_end or the dpws_endpoint_ref_array_free utility according to the fact that a dpws structure has been provided or not. If an error occurs or no proxy is found, NULL is returned. To distinguish between the two, use the res_size fields that is 0 is no endpoint were retrieved and -1 in case of error.

SOAP_FMAC1 void* SOAP_FMAC2 dpws_get_endpoint_user_data ( struct dpws dpws  ) 

Retrieves the user data associated to the endpoint that received the message.

Parameters:
dpws A pointer on the main DPWS API runtime data structure.
Returns:
A pointer on the data set on the device by the user.

SOAP_FMAC1 int SOAP_FMAC2 dpws_get_error ( struct dpws dpws  ) 

Returns the last DPWS or gSOAP runtime error.

Parameters:
dpws A pointer on a dpws data structure used when the error occured.
Returns:
A DPWS or gSOAP api error code.

SOAP_FMAC1 const char* SOAP_FMAC2 dpws_get_error_msg ( struct dpws dpws  ) 

Gets a message for a SOAP fault or a DPWS/gSOAP error that has previously occurred.

Parameters:
dpws A pointer on a dpws runtime data structure used when the error occured.
Returns:
A readonly error message.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
href_service A hosted service proxy handle reference.
Returns:
The host device proxy handle reference. -1 if not found.

SOAP_FMAC1 unsigned long SOAP_FMAC2 dpws_get_int_att ( short  href,
int  att 
)

Returns server object attributes of integer type (or boolean).

Parameters:
href The server object handle reference.
att The attribute identifier.
Returns:
The asked attribute value.

SOAP_FMAC1 struct wsa_endpoint_ref* SOAP_FMAC2 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.

Must be called after the call to dpws_server_init() or after the DPWS_STR_HTTP_ADDR attribute has been set on the toolkit.

Parameters:
service_port_href A service port handle reference.
Returns:
A heap allocated endpoint reference. The caller is responsible for liberation when no more needed (using dpws_endpoint_ref_free for instance).

SOAP_FMAC1 short SOAP_FMAC2 dpws_get_proxy_by_address ( char *  address  ) 

Retrieves a cached proxy handle reference basing on a physical address.

Parameters:
address the proxy physical address to be searched.
Returns:
the handle reference if retrieved. -1 else.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
id the proxy id to be searched.
Returns:
the handle reference if retrieved. -1 else.

SOAP_FMAC1 proxy_type SOAP_FMAC2 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.

Parameters:
href_proxy The service proxy handle reference (a device is also a service).
Returns:
An enum value representing the proxy type.

SOAP_FMAC1 void* SOAP_FMAC2 dpws_get_ptr_att ( short  href,
int  att 
)

Returns server object attributes for pointer types (string or not) attributes.

Parameters:
href The server object handle reference.
att The attribute identifier.
Returns:
A pointer to the asked attribute value. Must not be freed since no copy is performed. Multivalued attributes will be returned as NULL terminated arrays.

SOAP_FMAC1 void* SOAP_FMAC2 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.

Parameters:
href The server object handle reference.
att The attribute identifier.
index The index of the multivalued attribute.
Returns:
A pointer to the asked attribute value. Must not be freed since no copy is performed. Multivalued attributes will be returned as NULL terminated arrays.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
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.
Returns:
The retrieved service proxy handle reference, if available, -1 otherwise. Note: the returned endpoint is dynamically allocated on the gSOAP heap. This data is available until dpws_end is called to free memory.

The service proxy handle reference if found. -1, if not. The handle will be released during the next call to dpws_end in order to make associated resources available for liberation. To avoid the proxy to be freed and recycled, one should use the dpws_pin_proxy api. Note that between the moment it is retrieved and the one it is used, the proxy may become invalid.

SOAP_FMAC1 short SOAP_FMAC2 dpws_get_service_class_handle ( char *  id  ) 

Retrieves a service class handle by its id attribute.

Parameters:
id The service class id attribute.
Returns:
A handle reference, if found. -1 otherwise.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
device_href The device instance handle reference.
service_id the service identifier used as a key.
Returns:
A handle reference, if found. -1 otherwise.

SOAP_FMAC1 short SOAP_FMAC2 dpws_get_service_handle_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.

Parameters:
device_href The device instance handle reference.
service_class_href The service class handle reference used as a key.
Returns:
A handle reference, if found. -1 otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
device_href The device instance handle reference.
[in,out] hrefs A short array provided by the caller to receive results.
[in,out] len Must contain initially the length of the array hrefs. When the function returns it contains the number of results actually retrieved.
Returns:
DPWS_OK if the array supplied was large enough to receive results. 1, if extra-results are available.

SOAP_FMAC1 struct service_metadata* SOAP_FMAC2 dpws_get_service_metadata ( struct dpws dpws,
short  href_service 
)

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.

Parameters:
dpws A pointer on a dpws data structure used to process the request.
href_service A hosted service proxy handle reference.
Returns:
A structure containing metadata allocated on the dpws structure ( freed during the next call to dpws_end).

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
endpoint_href The (service) endpoint handle reference.
[in,out] hrefs A short array provided by the caller to receive results.
[in,out] len Must contain initially the length of the array hrefs. When the function returns it contains the number of results actually retrieved.
Returns:
DPWS_OK if the array supplied was large enough to receive results. 1, if extra-results are available.

SOAP_FMAC1 short* SOAP_FMAC2 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.

Parameters:
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.
Returns:
An array of svice proxy handle references that will be released during the next call to dpws_end in order to make associated resources available for liberation. To avoid the proxy to be freed and recycled, one should use the dpws_pin_proxy api. Note that between the moment it is retrieved and the one it is used, the proxy may become invalid. The size of the returned array can be retrieved using the output value of the res_size parameter. Note: the returned array is dynamically allocated on the gSOAP heap. This data is available until dpws_end is called to free memory. If an error occurs or no service is found, NULL is returned. To distinguish between the two, use the res_size fields that is 0 is no device were retrieved and -1 in case of error.

SOAP_FMAC1 char* SOAP_FMAC2 dpws_get_transport_address ( short  href_service_port  ) 

Builds the physical address for a local service port.

Must be called after the call to dpws_server_init().

Parameters:
href_service_port The handle for a local service port.
Returns:
A heap allocated URL. The caller is responsible for liberation when not needed anymore.

SOAP_FMAC1 int SOAP_FMAC2 dpws_init (  ) 

DPWS tookit initialization function.

Must be called before any other API call.

Returns:
a potential API error code.

SOAP_FMAC1 int SOAP_FMAC2 dpws_invalidate_proxy ( short  href  ) 

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

Parameters:
href The device or hosted service proxy href.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 short* SOAP_FMAC2 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 the MATCH_TIMEOUT constant defined in the WS-Discovery specifications and is 600 ms. To specify a custom value, use the dpws_lookup_ex API.

Parameters:
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.
Returns:
An array of device proxy handle references that will be released during the next call to dpws_end in order to make associated resources available for liberation. To avoid the proxy to be freed and recycled, one should use the dpws_pin_proxy api. Note that between the moment it is retrieved and the one it is used, the proxy may become invalid. The size of the returned array can be retrieved using the output value of the res_size parameter. Note: the returned array is dynamically allocated on the gSOAP heap. This data is available until dpws_end is called to free memory. If an error occurs or no device is found, NULL is returned. To distinguish between the two, use the res_size fields that is 0 is no device were retrieved and -1 in case of error.

SOAP_FMAC1 short SOAP_FMAC2 dpws_lookup_by_id ( struct dpws dpws,
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 MATCH_TIMEOUT constant defined in the WS-Discovery specifications and is 600 ms.

Parameters:
dpws A pointer on a dpws runtime data structure used to process the request.
uuid The device logical ID.
Returns:
The device proxy handle reference if found. -1, if not. The handle will be released during the next call to dpws_end in order to make associated resources available for liberation. To avoid the proxy to be freed and recycled, one should use the dpws_pin_proxy api. Note that between the moment it is retrieved and the one it is used, the proxy may become invalid.

SOAP_FMAC1 short* SOAP_FMAC2 dpws_lookup_ex ( struct dpws dpws,
struct qname types,
char **  scopes,
int  match_rule,
int *  res_size,
long  time_out,
int  mode 
)

Retrieves one or several device endpoints basing on types and scopes.

This function implements the semantics of the WS-Discovery Probe message, for a single device type. A matching device must match all the types and scopes provided to the API. This is the complete version of the lookup functions which enables fine-grained control of the API behavior.

Parameters:
dpws A pointer on a dpws runtime data structure used to process the request.
types A null-terminated qname struct array of port types used for filtering. The last element must be a qname struct filled with zeros.
scopes A null-terminated URI string array of scopes used for filtering.
match_rule The matching rule to be used for scope comparison. Should be one of:
  • WSD_MATCH_BY_RFC2396,
  • WSD_MATCH_BY_UUID,

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
href_proxy The proxy handle reference to be pin.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 short SOAP_FMAC2 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.

Parameters:
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).
Returns:
The device proxy handle reference if the device matched the requirements at the supplied address. -1, if not. The handle will be released during the next call to dpws_end in order to make associated resources available for liberation. To avoid the proxy to be freed and recycled, one should use the dpws_pin_proxy api. Note that between the moment it is retrieved and the one it is used, the proxy may become invalid.

SOAP_FMAC1 short SOAP_FMAC2 dpws_probe_address_ex ( struct dpws dpws,
char *  address,
struct qname types,
char **  scopes,
int  match_rule 
)

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.

Parameters:
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.
types A null-terminated qname struct array of port types used for filtering. The last element must be a qname struct filled with zeros.
scopes A null-terminated URI string array of scopes used for filtering.
match_rule The matching rule to be used for scope comparison. Should be one of:
  • WSD_MATCH_BY_RFC2396,
  • WSD_MATCH_BY_UUID,

SOAP_FMAC1 int SOAP_FMAC2 dpws_recv_empty_response ( struct dpws dpws  ) 

Receives one way or asynchronous empty response.

May be used only if a client wants to block waiting for and empty response.

Parameters:
dpws A pointer on a dpws runtime data structure.
Returns:
DPWS_OK, if no error occurred. A DPWS or gSOAP error code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 dpws_register_service_class ( short  device_class_href,
short  service_class_href 
)

Associates a service class to a device class.

Devices that will be created from the device class will host one service by service class registered to the device class. If the registration is not performed, hosted services will have to be created manually using dpws_create_hosted service. Note that the 65535 value is reserved.

Parameters:
device_class_href The device class handle reference.
service_class_href The service class handle reference.
Returns:
DPWS_OK, if no error occurred. A DPWS or gSOAP error code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
href The handle reference on the object to release.
Returns:
DPWS_OK, if no error occurred. A DPWS error code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
href_proxy The proxy handle reference to be released.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
dpws A pointer on a dpws data structure used to process the request.
Returns:
DPWS_OK, if no error occurred. A DPWS or gSOAP error code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 dpws_server_init ( struct dpws dpws,
struct wsa_endpoint_ref source 
)

Initialize the dpws structure and perform server-side initialization.

The initialization includes:

SOAP_FMAC1 struct localized_string** SOAP_FMAC2 dpws_set_device_friendly_names ( struct dpws dpws,
short  href_device,
struct localized_string **  names 
)

Changes a remote device friendly name that exposes the MDM service.

Parameters:
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.
names A NULL-terminated localized string array that specify the new friendly names for the device. NOTE: the current version of the toolkit only supports one friendly name so that the remote device may choose one name among the one supplied (basing on the preferred language).
Returns:
The friendly names actually set for the device (a NULL-terminated array). If null, may result from an API error or a remote fault.

SOAP_FMAC1 char** SOAP_FMAC2 dpws_set_device_scopes ( struct dpws dpws,
short  href_device,
char **  scopes 
)

Changes a remote device scope that exposes the MDM service.

Parameters:
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.
scopes A NULL-terminated URI array that specify the new scopes for the device.
Returns:
The scopes actually set for the device (a NULL-terminated URI array). If null, may result from an API error or a remote fault.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
href The server object handle reference.
att The attribute identifier.
value The integer parameter value.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
href The server object handle reference.
att The attribute identifier.
value The parameter value. Must be of the appropriate type, depending on the attribute.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Returns:
a potential API error code.

SOAP_FMAC1 int SOAP_FMAC2 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.

Parameters:
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.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 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.

Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 int SOAP_FMAC2 dpws_strcasecmp ( const char *  s1,
const char *  s2 
)

A portable version of a case-insensitive strcmp.

May be used to compare uuid, for instance.

Parameters:
s1 The first string to compare.
s2 The second string to compare.
Returns:
0 if strings are equal. <0 if s1 is alphabetically before s2. >0 else.

SOAP_FMAC1 int SOAP_FMAC2 dpws_update_metadata ( short  device_href  ) 

DPWS metadata change commit function.

This function must be called after a live update of a device metadata (increments metadata and send a hello). WARNING ! The current version DPWS does not really support "hot" configuration. This API was added for DPWS Interop Workshop (October 2005) purpose.

Parameters:
device_href The device handle reference.
Returns:
DPWS_OK, if no error occurred. A DPWS code otherwise.

SOAP_FMAC1 time_t SOAP_FMAC2 get_system_time (  ) 

Retrieves the system time in an UNIX-like date format.

Returns:
An absolute date featuring the seconds since 00:00:00 GMT,January 1,1970.

SOAP_FMAC1 char* SOAP_FMAC2 time2xmlduration ( char *  dest,
time_t  time 
)

Converts an UNIX-like date into an XML Schema duration value.

Parameters:
dest The buffer to receive the XML duration. Note that the DURATION_MAX_SIZE macro can be used to size the buffer.
time An absolute datetime to convert. The time features the seconds since 00:00:00 GMT,January 1,1970.
Returns:
An XML Schema duration calculated basing on the system time.

SOAP_FMAC1 time_t SOAP_FMAC2 xmlduration2time ( char *  xml_duration  ) 

Converts an XML Schema duration value into an UNIX-like date.

Parameters:
xml_duration A valid XML Schema duration.
Returns:
An absolute date calculated from the system time and the duration specified. The time features the seconds since 00:00:00 GMT,January 1,1970.


Generated on Mon May 7 19:15:42 2007 for DPWS Toolkit API Reference by  doxygen 1.5.1-p1