service client
[client API]


Files

file  axis2_svc_client.h

Defines

#define AXIS2_ANON_SERVICE   "__ANONYMOUS_SERVICE__"
#define AXIS2_ANON_OUT_ONLY_OP   "__OPERATION_OUT_ONLY__"
#define AXIS2_ANON_ROBUST_OUT_ONLY_OP   "__OPERATION_ROBUST_OUT_ONLY__"
#define AXIS2_ANON_OUT_IN_OP   "__OPERATION_OUT_IN__"
#define AXIS2_HTTP_PROXY_API   "PROXY_API"
#define AXIS2_HTTP_PROXY_HOST   "proxy_host"
#define AXIS2_HTTP_PROXY_PORT   "proxy_port"

Typedefs

typedef axis2_svc_client axis2_svc_client_t

Functions

AXIS2_EXTERN axis2_svc_taxis2_svc_client_get_svc (const axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t axis2_svc_client_set_options (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axis2_options_t *options)
AXIS2_EXTERN const axis2_options_taxis2_svc_client_get_options (const axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t axis2_svc_client_set_override_options (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axis2_options_t *override_options)
AXIS2_EXTERN const axis2_options_taxis2_svc_client_get_override_options (const axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t axis2_svc_client_engage_module (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axis2_char_t *module_name)
AXIS2_EXTERN axis2_status_t axis2_svc_client_disengage_module (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axis2_char_t *module_name)
AXIS2_EXTERN axis2_status_t axis2_svc_client_add_header (axis2_svc_client_t *svc_client, const axutil_env_t *env, axiom_node_t *header)
AXIS2_EXTERN axis2_status_t axis2_svc_client_remove_all_headers (axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t axis2_svc_client_send_robust_with_op_qname (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axutil_qname_t *op_qname, const axiom_node_t *payload)
AXIS2_EXTERN axis2_status_t axis2_svc_client_send_robust (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axiom_node_t *payload)
AXIS2_EXTERN void axis2_svc_client_fire_and_forget_with_op_qname (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axutil_qname_t *op_qname, const axiom_node_t *payload)
AXIS2_EXTERN void axis2_svc_client_fire_and_forget (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axiom_node_t *payload)
AXIS2_EXTERN axiom_node_t * axis2_svc_client_send_receive_with_op_qname (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axutil_qname_t *op_qname, const axiom_node_t *payload)
AXIS2_EXTERN axiom_node_t * axis2_svc_client_send_receive (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axiom_node_t *payload)
AXIS2_EXTERN void axis2_svc_client_send_receive_non_blocking_with_op_qname (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axutil_qname_t *op_qname, const axiom_node_t *payload, axis2_callback_t *callback)
AXIS2_EXTERN void axis2_svc_client_send_receive_non_blocking (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axiom_node_t *payload, axis2_callback_t *callback)
AXIS2_EXTERN axis2_op_client_taxis2_svc_client_create_op_client (axis2_svc_client_t *svc_client, const axutil_env_t *env, const axutil_qname_t *op_qname)
AXIS2_EXTERN axis2_status_t axis2_svc_client_finalize_invoke (axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN const axis2_endpoint_ref_taxis2_svc_client_get_own_endpoint_ref (const axis2_svc_client_t *svc_client, const axutil_env_t *env, const axis2_char_t *transport)
AXIS2_EXTERN const axis2_endpoint_ref_taxis2_svc_client_get_target_endpoint_ref (const axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t axis2_svc_client_set_target_endpoint_ref (axis2_svc_client_t *svc_client, const axutil_env_t *env, axis2_endpoint_ref_t *target_epr)
AXIS2_EXTERN axis2_status_t axis2_svc_client_set_proxy (axis2_svc_client_t *svc_client, const axutil_env_t *env, axis2_char_t *proxy_host, axis2_char_t *proxy_port)
AXIS2_EXTERN axis2_svc_ctx_taxis2_svc_client_get_svc_ctx (const axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN void axis2_svc_client_free (axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_op_client_taxis2_svc_client_get_op_client (const axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_svc_client_taxis2_svc_client_create (const axutil_env_t *env, const axis2_char_t *client_home)
AXIS2_EXTERN axis2_svc_client_taxis2_svc_client_create_with_conf_ctx_and_svc (const axutil_env_t *env, const axis2_char_t *client_home, axis2_conf_ctx_t *conf_ctx, axis2_svc_t *svc)
AXIS2_EXTERN axis2_svc_client_taxis2_svc_client_create_for_dynamic_invocation (const axutil_env_t *env, axis2_conf_ctx_t *conf_ctx, const axutil_uri_t *wsdl_uri, const axutil_qname_t *wsdl_svc_qname, const axis2_char_t *endpoint_name, const axis2_char_t *client_home)
AXIS2_EXTERN axiom_soap_envelope_t * axis2_svc_client_get_last_response_soap_envelope (const axis2_svc_client_t *svc_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_bool_t axis2_svc_client_get_last_response_has_fault (const axis2_svc_client_t *svc_client, const axutil_env_t *env)

Detailed Description

The service client interface serves as the primary client interface for consuming services. You can set the options to be used by the service client and then invoke an operation on a given service. There are several ways of invoking a service operation, which are based on the concept of a message exchange pattern (MEP). The two basic MEPs supported by service client are out-only and out-in. Each MEP can be used in either blocking or non-blocking mode. The operation invocations using the service client API are based on the XML-in/XML-out principle: both the payload to be sent to the service and the result from the service are in XML, represented in AXIOM.

Define Documentation

#define AXIS2_ANON_OUT_IN_OP   "__OPERATION_OUT_IN__"
 

out-in MEP operation name

#define AXIS2_ANON_OUT_ONLY_OP   "__OPERATION_OUT_ONLY__"
 

out-only MEP operation name

#define AXIS2_ANON_ROBUST_OUT_ONLY_OP   "__OPERATION_ROBUST_OUT_ONLY__"
 

out-only robust MEP operation name

#define AXIS2_ANON_SERVICE   "__ANONYMOUS_SERVICE__"
 

Name of anonymous service


Typedef Documentation

typedef struct axis2_svc_client axis2_svc_client_t
 

Type name for struct axis2_svc_client


Function Documentation

AXIS2_EXTERN axis2_status_t axis2_svc_client_add_header axis2_svc_client_t svc_client,
const axutil_env_t env,
axiom_node_t *  header
 

Adds an XML element as a header to be sent to the server side. This allows users to go beyond the usual XML-in/XML-out pattern, and send custom SOAP headers. Once added, service client owns the header and will clean up when the service client is freed.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
header om node representing the SOAP header in XML
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_svc_client_t* axis2_svc_client_create const axutil_env_t env,
const axis2_char_t *  client_home
 

Creates a service client struct.

Parameters:
env pointer to environment struct
client_home name of the directory that contains the Axis2/C repository
Returns:
a pointer to newly created service client struct, or NULL on error with error code set in environment's error

AXIS2_EXTERN axis2_svc_client_t* axis2_svc_client_create_for_dynamic_invocation const axutil_env_t env,
axis2_conf_ctx_t conf_ctx,
const axutil_uri_t *  wsdl_uri,
const axutil_qname_t *  wsdl_svc_qname,
const axis2_char_t *  endpoint_name,
const axis2_char_t *  client_home
 

Creates a service client struct. This constructor is used in dynamic invocation.

Parameters:
env pointer to environment struct
conf_ctx pointer to configuration context. Newly created client assumes ownership of the conf_ctx
wsdl_uri pointer to uri of the wsdl file.
wsdl_svc_qname pointer to qname of the wsdl service. If this is NULL first service is assumed
endpoint_name pointer to endpoint name. If this is NULL first endpoint is assumed.
client_home name of the directory that contains the Axis2/C repository
Returns:
a pointer to newly created service client struct, or NULL on error with error code set in environment's error

AXIS2_EXTERN axis2_op_client_t* axis2_svc_client_create_op_client axis2_svc_client_t svc_client,
const axutil_env_t env,
const axutil_qname_t *  op_qname
 

Creates an op_client for a specific operation. This is the way to create a full functional MEP client which can be used to exchange messages for this specific operation.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
op_qname axutil_qname_t of the operation
Returns:
pointer to newly created op_client configured for the given operation

AXIS2_EXTERN axis2_svc_client_t* axis2_svc_client_create_with_conf_ctx_and_svc const axutil_env_t env,
const axis2_char_t *  client_home,
axis2_conf_ctx_t conf_ctx,
axis2_svc_t svc
 

Creates a service client struct for a specified service and configuration context.

Parameters:
env pointer to environment struct
conf_ctx pointer to configuration context. Newly created client assumes ownership of the conf_ctx
svc pointer to service struct representing the service to be consumed. Newly created client assumes ownership of the service
client_home name of the directory that contains the Axis2/C repository
Returns:
a pointer to newly created service client struct, or NULL on error with error code set in environment's error

AXIS2_EXTERN axis2_status_t axis2_svc_client_disengage_module axis2_svc_client_t svc_client,
const axutil_env_t env,
const axis2_char_t *  module_name
 

Dis-engages the named module. Dis-engaging a module on a service client ensures that the axis2_engine would not invoke the named module when sending and receiving messages.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
module_name name of the module to be dis-engaged
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_svc_client_engage_module axis2_svc_client_t svc_client,
const axutil_env_t env,
const axis2_char_t *  module_name
 

Engages the named module. The engaged modules extend the message processing when consuming services. Modules help to apply QoS norms in messaging. Once a module is engaged to a service client, the axis2_engine makes sure to invoke the module for all the interactions between the client and the service.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
module_name name of the module to be engaged
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_svc_client_finalize_invoke axis2_svc_client_t svc_client,
const axutil_env_t env
 

Cleans up service client invocation. This will close the output stream and/or remove entry from waiting queue of the transport listener queue.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN void axis2_svc_client_fire_and_forget axis2_svc_client_t svc_client,
const axutil_env_t env,
const axiom_node_t *  payload
 

Sends a message and forget about it. This method is used to interact with a service operation whose MEP is In-Only. That is, there is no opportunity to get an error from the service via this method; one may still get client-side errors, such as host unknown etc.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
payload pointer to OM node representing the XML payload to be sent

AXIS2_EXTERN void axis2_svc_client_fire_and_forget_with_op_qname axis2_svc_client_t svc_client,
const axutil_env_t env,
const axutil_qname_t *  op_qname,
const axiom_node_t *  payload
 

Sends a message and forget about it. This method is used to interact with a service operation whose MEP is In-Only. That is, there is no opportunity to get an error from the service via this method; one may still get client-side errors, such as host unknown etc.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
op_qname operation qname. NULL is equivalent to an operation name of "__OPERATION_OUT_ONLY__"
payload pointer to OM node representing the XML payload to be sent

AXIS2_EXTERN void axis2_svc_client_free axis2_svc_client_t svc_client,
const axutil_env_t env
 

Frees the service client.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_bool_t axis2_svc_client_get_last_response_has_fault const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Gets the boolean value indicating if the last respose had a SOAP fault.

Parameters:
svc_client pointer to service_client struct
env env pointer to environemt struct
Returns:
AXIS2_TRUE if there was a fault, else AXIS2_FALSE

AXIS2_EXTERN axiom_soap_envelope_t* axis2_svc_client_get_last_response_soap_envelope const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Gets the last respose SOAP envelope.

Parameters:
svc_client pointer to service_client struct
env env pointer to environemt struct
Returns:
pointer to SOAP envelope that was returned as a result when send_receieve was called last time

AXIS2_EXTERN axis2_op_client_t* axis2_svc_client_get_op_client const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Gets the operation client

Parameters:
svc_client pointer to service_client struct
env env pointer to environemt struct
Returns:
pointer to service context struct. service client owns the returned pointer

AXIS2_EXTERN const axis2_options_t* axis2_svc_client_get_options const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Gets options used by service client.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
a pointer to the options struct if options set, else NULL. Returns a reference, not a cloned copy.

AXIS2_EXTERN const axis2_options_t* axis2_svc_client_get_override_options const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Gets the overriding options.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
pointer to overriding options struct if options set, else NULL. Returns a reference, not a cloned copy.

AXIS2_EXTERN const axis2_endpoint_ref_t* axis2_svc_client_get_own_endpoint_ref const axis2_svc_client_t svc_client,
const axutil_env_t env,
const axis2_char_t *  transport
 

Gets the service client's own endpoint_ref, that is the endpoint the client will be sending from.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
transport name of the transport, e.g "http"
Returns:
pointer to the endpoint_ref struct. Returns a reference, not a cloned copy.

AXIS2_EXTERN axis2_svc_t* axis2_svc_client_get_svc const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Returns the axis2_svc_t this is a client for. This is primarily useful when the service is created anonymously or from WSDL.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
a pointer to axis service struct, or NULL if no service is associated. Returns a reference, not a cloned copy.

AXIS2_EXTERN axis2_svc_ctx_t* axis2_svc_client_get_svc_ctx const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Gets the service context.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
pointer to service context struct. service client owns the returned pointer.

AXIS2_EXTERN const axis2_endpoint_ref_t* axis2_svc_client_get_target_endpoint_ref const axis2_svc_client_t svc_client,
const axutil_env_t env
 

Gets the target endpoint ref.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
pointer to the endpoint_ref struct. Returns a reference, not a cloned copy.

AXIS2_EXTERN axis2_status_t axis2_svc_client_remove_all_headers axis2_svc_client_t svc_client,
const axutil_env_t env
 

Removes all the headers added to service client.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axiom_node_t* axis2_svc_client_send_receive axis2_svc_client_t svc_client,
const axutil_env_t env,
const axiom_node_t *  payload
 

Sends XML request and receives XML response. This method is used to interact with a service operation whose MEP is In-Out.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
payload pointer to OM node representing the XML payload to be sent
Returns:
pointer to OM node representing the XML response. The caller owns the returned node.

AXIS2_EXTERN void axis2_svc_client_send_receive_non_blocking axis2_svc_client_t svc_client,
const axutil_env_t env,
const axiom_node_t *  payload,
axis2_callback_t callback
 

Sends XML request and receives XML response, but does not block for response. This method is used to interact in non-blocking mode with a service operation whose MEP is In-Out.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
payload pointer to OM node representing the XML payload to be sent pointer to callback struct used to capture response

AXIS2_EXTERN void axis2_svc_client_send_receive_non_blocking_with_op_qname axis2_svc_client_t svc_client,
const axutil_env_t env,
const axutil_qname_t *  op_qname,
const axiom_node_t *  payload,
axis2_callback_t callback
 

Sends XML request and receives XML response, but does not block for response. This method is used to interact in non-blocking mode with a service operation whose MEP is In-Out.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
op_qname operation qname. NULL is equivalent to an operation name of "__OPERATION_OUT_IN__"
payload pointer to OM node representing the XML payload to be sent pointer to callback struct used to capture response

AXIS2_EXTERN axiom_node_t* axis2_svc_client_send_receive_with_op_qname axis2_svc_client_t svc_client,
const axutil_env_t env,
const axutil_qname_t *  op_qname,
const axiom_node_t *  payload
 

Sends XML request and receives XML response. This method is used to interact with a service operation whose MEP is In-Out.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
op_qname operation qname. NULL is equivalent to an operation name of "__OPERATION_OUT_IN__"
payload pointer to OM node representing the XML payload to be sent
Returns:
pointer to OM node representing the XML response. The caller owns the returned node.

AXIS2_EXTERN axis2_status_t axis2_svc_client_send_robust axis2_svc_client_t svc_client,
const axutil_env_t env,
const axiom_node_t *  payload
 

This method can be used to send an XML message. This is a simple method to invoke a service operation whose MEP is Robust Out-Only. If a fault triggers on server side, this method would report an error back to the caller.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct operation name of "__OPERATION_ROBUST_OUT_ONLY__"
payload pointer to OM node representing the XML payload to be sent
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_svc_client_send_robust_with_op_qname axis2_svc_client_t svc_client,
const axutil_env_t env,
const axutil_qname_t *  op_qname,
const axiom_node_t *  payload
 

This method can be used to send an XML message. This is a simple method to invoke a service operation whose MEP is Robust Out-Only. If a fault triggers on server side, this method would report an error back to the caller.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
op_qname operation qname. NULL is equivalent to an operation name of "__OPERATION_ROBUST_OUT_ONLY__"
payload pointer to OM node representing the XML payload to be sent
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_svc_client_set_options axis2_svc_client_t svc_client,
const axutil_env_t env,
const axis2_options_t options
 

Sets the options to be used by service client.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
options pointer to options struct to be set
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_svc_client_set_override_options axis2_svc_client_t svc_client,
const axutil_env_t env,
const axis2_options_t override_options
 

Sets the overriding options. The overriding client options related to this service interaction override any options that the underlying operation client may have.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
options pointer to options struct to be set
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_svc_client_set_proxy axis2_svc_client_t svc_client,
const axutil_env_t env,
axis2_char_t *  proxy_host,
axis2_char_t *  proxy_port
 

Sets the proxy.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
proxy_host pointer to the proxy_host settings to be set as
proxy_port pointer to the proxy_port settings to be set as target. service client takes over the ownership of the struct.
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_svc_client_set_target_endpoint_ref axis2_svc_client_t svc_client,
const axutil_env_t env,
axis2_endpoint_ref_t target_epr
 

Sets the target endpoint ref.

Parameters:
svc_client pointer to service client struct
env pointer to environment struct
target_epr pointer to the endpoint_ref struct to be set as target. service client takes over the ownership of the struct.
Returns:
AXIS2_SUCCESS on success, else AXIS2_FAILURE


Generated on Thu May 3 12:31:03 2007 for Axis2/C by  doxygen 1.4.6