dc_XMLConfiguration.h File Reference

API for the XML configuration feature. More...

#include "dc/dc_Dpws.h"

Data Structures

struct  scl_callbacks
 A structure that groups all callbacks a service class loader returns. More...

Defines

XML configuration errors
These code extend DPWS error codes.

#define DPWS_ERR_NO_LOADER_FOUND   -200
 The service loader could not be found for the implementation tag.
#define DPWS_ERR_NO_DISPATCH_FUNC   -201
 The service loader did not return the dispatch function for the service.
#define DPWS_ERR_NO_SERIALIZE_IMPL_FUNC   -202
 The service loader did not return the callback to serialize.
#define DPWS_ERR_INCORRECT_IMPL_TAG   -203
 The service loader could not parse the implementation tag.
#define DPWS_ERR_OPTIONAL_REF_MISSING   -204
 Not an error: the asked reference is missing but optional.
#define DPWS_ERR_MANDATORY_REF_MISSING   -205
 The asked mandatory reference is missing.
#define DPWS_ERR_COULD_NOT_BIND_IGNORE   -206
 The reference could not be bound but is ignorable.
#define DPWS_ERR_COULD_NOT_BIND_RETRY   -207
 The reference could not be bound: the service is supposed to retry later.
#define DPWS_ERR_COULD_NOT_BIND_FAIL   -208
 The reference could not be bound: the service is supposed to enter in fault mode.
#define DPWS_ERR_MULTIPLE_REFERENCE   -209
 The reference was bound to multiple endpoints which is not supported.
#define DPWS_ERR_STATIC_REFERENCE   -210
 The reference cannot be invalidated since it is static.
#define DPWS_ERR_LNAME_TOO_LONG   -211
 A local name in the configuration file exceeds the internal buffer.
#define DPWS_ERR_RESOURCE_ALREADY_EXIST   -212
 The resource already exists in the registry.
#define DPWS_ERR_SERVICE_NOT_FOUND   -213
 The hosted service was not found in the registry.
#define DPWS_ERR_SERVICE_CLASS_NOT_FOUND   -214
 The service class was not found in the registry.
#define DPWS_ERR_SUN_RESOURCE   -215
 The SUN resource could not be found.
XML grammatical errors
#define DPWS_ERR_TAG_MISMATCH   101
 The tag was not expected.
#define DPWS_ERR_EVENT_MISMATCH   102
 The EPX event was not expected.
#define DPWS_ERR_MISSING_PARTICLE   104
 An expected element is missing.
#define DPWS_ERR_TOO_MANY_OCCURENCES   105
 An element occurred too many times.
#define DPWS_ERR_UNEXPECTED_PARTICLE   106
 An expected element was encountered.
#define DPWS_ERR_MISSING_EXPECTED_ELT   107
 Not enough element occurrences.
#define DPWS_ERR_MISSING_REQUIRED_ATT   108
 A required attribute is missing.
#define DPWS_ERR_INVALID_ENUM   110
 A value does not belong to the enumeration.

Functions

Initialization API
DC_RT_FMAC1 int dpws_config_init ()
 Initialize the XML configuration features.
DC_RT_FMAC1 int dpws_config_shutdown ()
 Shutdown the XML configuration features.
Reference API
DC_RT_FMAC1 int dpws_lookup_binding_ref (struct dpws *dpws, short href_service, const char *name, struct wsa_endpoint_ref **epr)
 To call the first time an EPR is needed for WS invocation.
DC_RT_FMAC1 int dpws_bind_reference (struct dpws *dpws, short href_service, const char *name, struct wsa_endpoint_ref **epr)
 To call when a previously retrieved EPR is invalid (invocation error).
Property API
DC_RT_FMAC1 int dpws_get_property_values (short href_service, char *property, char **values, int *len)
 Retrieves property values for a service.

XML Configuration persistence API

#define DPWS_CONFIG_DEFAULT_ID   "dpwscore.xml"
 A default name for the DPWSCore configuration "file".
DC_RT_FMAC1 int dpws_load_config (void *psr_ctx)
 Load the DPWS registry from an EPX input stream.
DC_RT_FMAC1 int dpws_save_config (void *szr_ctx, DC_BOOL inc_boot_seq, DC_BOOL as_fragment)
 Saves the DPWS registry into an EPX output stream.
DC_RT_FMAC1 int dpws_sun_load_config (struct dpws *dpws, void *sun_in_stream)
 Load the DPWS registry using the SUN persistency layer.
DC_RT_FMAC1 int dpws_sun_save_config (struct dpws *dpws, void *sun_out_stream, DC_BOOL inc_boot_seq)
 Saves the DPWS registry using the SUN persistency layer.

Dynamic Loader API

typedef int(* new_service_cbk )(short href_endpoint)
 This callback will be called when the service is instantiated by the dynamic deployment service so that the implementation is able, for instance, to create the user data for the service.
typedef int(* free_service_cbk )(short href_endpoint)
 This callback will be called when the service is destroyed by the dynamic deployment service so that the implementation is able, for instance, to free the user data for the service.
typedef int(* serialize_impl_cbk )(short href_sclass, void *szr_ctx)
 This callback will be called when the dynamic deployment service needs to get back the implementation tag in order to return it in a response or make it persistent.
typedef int(* unload_impl_cbk )(short href_sclass)
 This callback will be called when the service class is deleted by the deployment srevice.
typedef int(* load_cbk )(short href_sclass, void *psr_ctx, dispatch_cbk *p_dispatch_cbk, struct scl_callbacks *p_cbks)
 This callback is exposed by a loader and called by the dynamic deployment service when an implementation tag is parsed and service class is created.
DC_RT_FMAC1 int dpws_register_loader (const struct qname *id, load_cbk cbk)
 Register a dynamic loader to the dynamic deployment service.


Detailed Description

API for the XML configuration feature.

The XML configuration feature is also the core for dynamic deployment since it shares most of the dynamic deployment descriptor XML format.


Define Documentation

#define DPWS_ERR_NO_LOADER_FOUND   -200

The service loader could not be found for the implementation tag.

#define DPWS_ERR_NO_DISPATCH_FUNC   -201

The service loader did not return the dispatch function for the service.

#define DPWS_ERR_NO_SERIALIZE_IMPL_FUNC   -202

The service loader did not return the callback to serialize.

#define DPWS_ERR_INCORRECT_IMPL_TAG   -203

The service loader could not parse the implementation tag.

#define DPWS_ERR_OPTIONAL_REF_MISSING   -204

Not an error: the asked reference is missing but optional.

#define DPWS_ERR_MANDATORY_REF_MISSING   -205

The asked mandatory reference is missing.

#define DPWS_ERR_COULD_NOT_BIND_IGNORE   -206

The reference could not be bound but is ignorable.

#define DPWS_ERR_COULD_NOT_BIND_RETRY   -207

The reference could not be bound: the service is supposed to retry later.

#define DPWS_ERR_COULD_NOT_BIND_FAIL   -208

The reference could not be bound: the service is supposed to enter in fault mode.

#define DPWS_ERR_MULTIPLE_REFERENCE   -209

The reference was bound to multiple endpoints which is not supported.

#define DPWS_ERR_STATIC_REFERENCE   -210

The reference cannot be invalidated since it is static.

#define DPWS_ERR_LNAME_TOO_LONG   -211

A local name in the configuration file exceeds the internal buffer.

#define DPWS_ERR_RESOURCE_ALREADY_EXIST   -212

The resource already exists in the registry.

#define DPWS_ERR_SERVICE_NOT_FOUND   -213

The hosted service was not found in the registry.

#define DPWS_ERR_SERVICE_CLASS_NOT_FOUND   -214

The service class was not found in the registry.

#define DPWS_ERR_SUN_RESOURCE   -215

The SUN resource could not be found.

See SUN implementation error code

#define DPWS_ERR_TAG_MISMATCH   101

The tag was not expected.

#define DPWS_ERR_EVENT_MISMATCH   102

The EPX event was not expected.

#define DPWS_ERR_MISSING_PARTICLE   104

An expected element is missing.

#define DPWS_ERR_TOO_MANY_OCCURENCES   105

An element occurred too many times.

#define DPWS_ERR_UNEXPECTED_PARTICLE   106

An expected element was encountered.

#define DPWS_ERR_MISSING_EXPECTED_ELT   107

Not enough element occurrences.

#define DPWS_ERR_MISSING_REQUIRED_ATT   108

A required attribute is missing.

#define DPWS_ERR_INVALID_ENUM   110

A value does not belong to the enumeration.

#define DPWS_CONFIG_DEFAULT_ID   "dpwscore.xml"

A default name for the DPWSCore configuration "file".


Typedef Documentation

typedef int(* new_service_cbk)(short href_endpoint)

This callback will be called when the service is instantiated by the dynamic deployment service so that the implementation is able, for instance, to create the user data for the service.

Warning: Note that the service was already created in the DC registry but not in the "Dynamic Deployment" configuration so references and properties are not usable yet.

Parameters:
href_endpoint The hosted service handle that was created and that can be used by the loader to retrieve the implementation.
Returns:
A DPWS error code.

typedef int(* free_service_cbk)(short href_endpoint)

This callback will be called when the service is destroyed by the dynamic deployment service so that the implementation is able, for instance, to free the user data for the service.

Parameters:
href_endpoint The hosted service handle that was created and that can be used by the loader to retrieve the implementation.
Returns:
A DPWS error code.

typedef int(* serialize_impl_cbk)(short href_sclass, void *szr_ctx)

This callback will be called when the dynamic deployment service needs to get back the implementation tag in order to return it in a response or make it persistent.

Parameters:
href_sclass The service class handle that was passed initially to the loader through the load callback.
szr_ctx The EPX serialization context for the implementation tag restoration.
Returns:
DPWS_OK or a DPWSCore error code if an error occurred.

typedef int(* unload_impl_cbk)(short href_sclass)

This callback will be called when the service class is deleted by the deployment srevice.

Parameters:
href_sclass The service class handle that was passed initially to the loader through the load callback.
Returns:
DPWS_OK or a DPWSCore error code if an error occured.

typedef int(* load_cbk)(short href_sclass, void *psr_ctx, dispatch_cbk *p_dispatch_cbk, struct scl_callbacks *p_cbks)

This callback is exposed by a loader and called by the dynamic deployment service when an implementation tag is parsed and service class is created.

Parameters:
href_sclass The service class handle that is being created by the dynamic deployment service.
psr_ctx The callback is responsible for parsing the content until the END_ELEMENT event of the implementation tag.
[out] p_dispatch_cbk The loader should return a DPWSCore dispatch function. Only the serialization callback is mandatory.
[in,out] p_cbks The loader should fill the passed structured with the expected callbacks.
Returns:
DPWS_OK or a DPWSCore error code if an error occured.


Function Documentation

DC_RT_FMAC1 int dpws_config_init (  ) 

Initialize the XML configuration features.

Must be called before any other call.

Returns:
DPWS_OK or a DPWSCore error code if an error occurred.

DC_RT_FMAC1 int dpws_config_shutdown (  ) 

Shutdown the XML configuration features.

Returns:
DPWS_OK or a DPWSCore error code if an error occurred.

DC_RT_FMAC1 int dpws_register_loader ( const struct qname id,
load_cbk  cbk 
)

Register a dynamic loader to the dynamic deployment service.

Parameters:
id The dynamic deployment descriptor implementation tag expanded name which identifies the loader.
cbk The loader callback called by the dynamic deployment service when an implementation tag is encountered.
Returns:
DPWS_OK or a DPWSCore error code if an error occured.

DC_RT_FMAC1 int dpws_lookup_binding_ref ( struct dpws dpws,
short  href_service,
const char *  name,
struct wsa_endpoint_ref **  epr 
)

To call the first time an EPR is needed for WS invocation.

Parameters:
dpws A pointer on the main DPWS API runtime data structure used to perform potential WS-Discovery operations.
href_service The handle reference of the service endpoint to which the binding reference is attached.
name The name of the binding.
[out] epr The return read-only EPR that must not be freed after use. The EPR should be kept and used until an error occurs using it after what a call to dpws_bind_reference may be required.
Returns:
An API error code among which DPWS_ERR_COULD_NOT_BIND_IGNORE, DPWS_ERR_COULD_NOT_BIND_RETRY and DPWS_ERR_COULD_NOT_BIND_FAIL should give the caller the required behavior asked for the reference.

DC_RT_FMAC1 int dpws_bind_reference ( struct dpws dpws,
short  href_service,
const char *  name,
struct wsa_endpoint_ref **  epr 
)

To call when a previously retrieved EPR is invalid (invocation error).

Parameters:
dpws A pointer on the main DPWS API runtime data structure used to perform potential WS-Discovery operations.
href_service The handle reference of the service endpoint to which the binding reference is attached.
name The name of the binding.
[out] epr The return read-only EPR that must not be freed after use.
[out] epr The return read-only EPR that must not be freed after use. The EPR should be kept and used until an error occurs using it after what a call to dpws_bind_reference may be required.
Returns:
An API error code among which DPWS_ERR_COULD_NOT_BIND_IGNORE, DPWS_ERR_COULD_NOT_BIND_RETRY and DPWS_ERR_COULD_NOT_BIND_FAIL should give the caller the required behavior asked for the reference. DPWS_ERR_STATIC_REFERENCE will be returned if the binding reference is defined as an EPR.

DC_RT_FMAC1 int dpws_get_property_values ( short  href_service,
char *  property,
char **  values,
int *  len 
)

Retrieves property values for a service.

Parameters:
href_service The service handle reference.
property The property name.
[in,out] values A string array provided by the caller to receive results. Note that the returned strings should not be released (read-only).
[in,out] len Must contain initially the length of the string array. 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. DPWS_ERR_MORE_RESULTS, if extra-results are available.

DC_RT_FMAC1 int dpws_load_config ( void *  psr_ctx  ) 

Load the DPWS registry from an EPX input stream.

This API should be used before the call to dpws_server_init.

Parameters:
psr_ctx The EPX parsing context.
Returns:
DPWS_OK if no error occurred. Otherwise, a DPWS error code (negative values) or a parsing error (positive) from gSOAP (I/O or syntactic error) or SGXP (grammatical error defined in dcXTOOL_SchemaParsing.h).

DC_RT_FMAC1 int dpws_save_config ( void *  szr_ctx,
DC_BOOL  inc_boot_seq,
DC_BOOL  as_fragment 
)

Saves the DPWS registry into an EPX output stream.

Parameters:
szr_ctx The EPX serialization context.
inc_boot_seq If DC_TRUE, the boot sequence is incremented before.
as_fragment If DC_TRUE, the event stream is produced without start/end document events.
Returns:
0 if no error occurred. Otherwise, an EPX implementation error code (gSOAP error code).

DC_RT_FMAC1 int dpws_sun_load_config ( struct dpws dpws,
void *  sun_in_stream 
)

Load the DPWS registry using the SUN persistency layer.

This API should be used before the call to dpws_server_init.

Parameters:
dpws A DPWS runtime structure used for SUN serialization.
sun_in_stream Storage unit implementation-dependent opened input stream. The stream will be closed automatically at the end of processing.
Returns:
DPWS_OK if no error occurred. Otherwise, a DPWS error code (negative values) or a parsing error (positive) from gSOAP (I/O or syntactic error) or SGXP (grammatical error defined in dcXTOOL_SchemaParsing.h).

DC_RT_FMAC1 int dpws_sun_save_config ( struct dpws dpws,
void *  sun_out_stream,
DC_BOOL  inc_boot_seq 
)

Saves the DPWS registry using the SUN persistency layer.

Parameters:
dpws A DPWS runtime structure used for SUN serialization.
sun_out_stream Storage unit implementation-dependent opened output stream. The stream will be closed automatically at the end of processing.
inc_boot_seq If DC_TRUE, the boot sequence is incremented before.
Returns:
0 if no error occurred. Otherwise, an EPX implementation error code (gSOAP error code).


Generated on Fri Apr 17 15:18:25 2009 for DPWSCore by  doxygen 1.5.8