# operation client
[client API]

## Files
file | axis2_op_client.h
## Typedefs
typedef struct axis2_op_client | axis2_op_client_t
## Functions
AXIS2_EXTERN axis2_status_t | axis2_op_client_set_options (axis2_op_client_t *op_client, const axutil_env_t *env, const axis2_options_t *options)
AXIS2_EXTERN const axis2_options_t * | axis2_op_client_get_options (const axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_op_client_add_msg_ctx (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_msg_ctx_t *msg_ctx)
AXIS2_EXTERN axis2_status_t | axis2_op_client_add_out_msg_ctx (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_msg_ctx_t *msg_ctx)
AXIS2_EXTERN axis2_status_t | axis2_op_client_add_in_msg_ctx (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_msg_ctx_t *msg_ctx)
AXIS2_EXTERN const axis2_msg_ctx_t * | axis2_op_client_get_msg_ctx (const axis2_op_client_t *op_client, const axutil_env_t *env, const axis2_wsdl_msg_labels_t message_label)
AXIS2_EXTERN axis2_status_t | axis2_op_client_set_callback (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_callback_t *callback)
AXIS2_EXTERN axis2_callback_t * | axis2_op_client_get_callback (axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_op_client_execute (axis2_op_client_t *op_client, const axutil_env_t *env, const axis2_bool_t block)
AXIS2_EXTERN axis2_status_t | axis2_op_client_reset (axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_op_client_complete (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_msg_ctx_t *msg_ctx)
AXIS2_EXTERN axis2_op_ctx_t * | axis2_op_client_get_operation_context (const axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_op_client_set_callback_recv (axis2_op_client_t *op_client, const axutil_env_t *env, struct axis2_callback_recv *callback_recv)
AXIS2_EXTERN void | axis2_op_client_free (axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_op_client_t * | axis2_op_client_create (const axutil_env_t *env, axis2_op_t *op, axis2_svc_ctx_t *svc_ctx, axis2_options_t *options)
AXIS2_EXTERN axutil_string_t * | axis2_op_client_get_soap_action (const axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_op_client_prepare_invocation (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_op_t *op, axis2_msg_ctx_t *msg_ctx)
AXIS2_EXTERN axis2_msg_ctx_t * | axis2_op_client_prepare_soap_envelope (axis2_op_client_t *op_client, const axutil_env_t *env, axiom_node_t *to_send)
AXIS2_EXTERN axis2_transport_out_desc_t * | axis2_op_client_infer_transport (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_endpoint_ref_t *epr)
AXIS2_EXTERN axiom_soap_envelope_t * | axis2_op_client_create_default_soap_envelope (axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_op_client_engage_module (axis2_op_client_t *op_client, const axutil_env_t *env, const axutil_qname_t *qname)
AXIS2_EXTERN axis2_status_t | axis2_op_client_set_soap_version_uri (axis2_op_client_t *op_client, const axutil_env_t *env, const axis2_char_t *soap_version_uri)
AXIS2_EXTERN axis2_status_t | axis2_op_client_set_soap_action (axis2_op_client_t *op_client, const axutil_env_t *env, axutil_string_t *soap_action)
AXIS2_EXTERN axis2_status_t | axis2_op_client_set_wsa_action (axis2_op_client_t *op_client, const axutil_env_t *env, const axis2_char_t *wsa_action)
AXIS2_EXTERN axis2_svc_ctx_t * | axis2_op_client_get_svc_ctx (const axis2_op_client_t *op_client, const axutil_env_t *env)
AXIS2_EXTERN void | axis2_op_client_set_reuse (axis2_op_client_t *op_client, const axutil_env_t *env, axis2_bool_t reuse)
AXIS2_EXTERN axis2_msg_ctx_t * | axis2_op_client_two_way_send (const axutil_env_t *env, axis2_msg_ctx_t *msg_ctx)
AXIS2_EXTERN axis2_msg_ctx_t * | axis2_op_client_receive (const axutil_env_t *env, axis2_msg_ctx_t *msg_ctx)

## Detailed Description

The operation client is meant to be used by advanced users to consume services. Operation client understands a specific Message Exchange Pattern (op) and hence the behavior is defined by the op. To consume services with an operation client, an operation (of type axis2_op_t) and a service context (of type axis2_svc_ctx_t) has to be provided along with options to be used. The execute() function can be used to send the request and get the response. The service client implementation uses the operation client and provides an easy to use API for consuming services. Hence the service client implementation is a very good example of how to use the operation client API.

See also:
  service client

## Typedef Documentation

typedef struct axis2_op_client axis2_op_client_t

Type name for struct axis2_op_client

## Function Documentation

AXIS2_EXTERN axis2_status_t axis2_op_client_add_msg_ctx | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axis2_msg_ctx_t * | msg_ctx |
| ) |  |  |

Adds a message context to the client for processing.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct
  | msg_ctx | message context to be added. operation client takes over the ownership of the message context struct.

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_add_out_msg_ctx | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axis2_msg_ctx_t * | msg_ctx |
| ) |  |  |

Adds out message context to the client for processing.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct
  | msg_ctx | message context to be added. operation client takes over the ownership of the message context struct.

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_complete | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axis2_msg_ctx_t * | msg_ctx |
| ) |  |  |

Completes the execution by closing the transports if necessary. This method is useful when client uses two transports for sending and receiving.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct
  | msg_ctx | message context which contains the transport information

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_op_client_t* axis2_op_client_create | ( | const axutil_env_t * | env,
|  | axis2_op_t * | op,
|  | axis2_svc_ctx_t * | svc_ctx,
|  | axis2_options_t * | options |
| ) |  |  |

Creates an operation client struct for the specified operation, service context and given options.

Parameters:

  | env | pointer to environment struct
  | op | pointer to operation struct corresponding to the operation to to be executed. Newly created client assumes ownership of the operation.
  | svc_ctx | pointer to service context struct representing the service to be consumed. Newly created client assumes ownership of the service context.
  | options | options to be used by operation client. Newly created client assumes ownership of the options context.

Returns:
  a pointer to newly created operation client struct, or NULL on error with error code set in environment's error

AXIS2_EXTERN axiom_soap_envelope_t* axis2_op_client_create_default_soap_envelope | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Creates default SOAP envelope.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct

Returns:
  pointer to default SOAP envelope created

AXIS2_EXTERN axis2_status_t axis2_op_client_engage_module | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | const axutil_qname_t * | qname |
| ) |  |  |

Engage named module. The named module must have been configured in the Axis2 configuration. For a module to be detected by the deployment engine, the modules has to be placed in the AXIS2_REPOSITORY/modules directory.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | qname | QName representing the module name

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_execute | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | const axis2_bool_t | block |
| ) |  |  |

Execute the op. What this does depends on the specific operation client. The basic idea is to have the operation client execute and do something with the messages that have been added to it so far. For example, if its an Out-In op, and if the Out message has been set, then executing the client asks it to send the out message and get the in message

Parameters:

  | op_client | pointer to operation client
  | env | pointer to environment struct
  | block | indicates whether execution should block or return ASAP

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN void axis2_op_client_free | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Frees the operation client

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct

Returns:
  void

AXIS2_EXTERN axis2_callback_t* axis2_op_client_get_callback | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets the callback.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct

Returns:
  callback

AXIS2_EXTERN const axis2_msg_ctx_t* axis2_op_client_get_msg_ctx | ( | const axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | const axis2_wsdl_msg_labels_t | message_label |
| ) |  |  |

Gets a message corresponding to the given label.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct
  | message_label | the message label of the desired message context

Returns:
  the desired message context or NULL if its not available. Returns a reference, not a cloned copy.

AXIS2_EXTERN axis2_op_ctx_t* axis2_op_client_get_operation_context | ( | const axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets the operation context of the operation client.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct

Returns:
  operation context related to operation client

AXIS2_EXTERN const axis2_options_t* axis2_op_client_get_options | ( | const axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets options used by operation client.

Parameters:

  | op_client | pointer to operation 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 axutil_string_t* axis2_op_client_get_soap_action | ( | const axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets SOAP action.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct

Returns:
  a pointer to SOAP action string

AXIS2_EXTERN axis2_svc_ctx_t* axis2_op_client_get_svc_ctx | ( | const axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets service context.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct

Returns:
  pointer to service context struct if set, else NULL

AXIS2_EXTERN axis2_transport_out_desc_t* axis2_op_client_infer_transport | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axis2_endpoint_ref_t * | epr |
| ) |  |  |

Tries to infer the transport looking at the URL, the URL can be http:// tcp:// mail:// local://. The method will look for the transport name as the protocol part of the transport.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | epr | endpoint reference struct representing the endpoint URL

Returns:
  pointer to the transport description with inferred information

AXIS2_EXTERN axis2_status_t axis2_op_client_prepare_invocation | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axis2_op_t * | op,
|  | axis2_msg_ctx_t * | msg_ctx |
| ) |  |  |

Prepares the message context for invocation. Here the properties kept in the op_client are copied to the message context.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | op | pointer operation to be invoked
  | msg_ctx | pointer to message context to be filled

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_msg_ctx_t* axis2_op_client_prepare_soap_envelope | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axiom_node_t * | to_send |
| ) |  |  |

Prepares the SOAP envelope using the payload.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | to_send | payload to be sent in AXIOM node format

Returns:
  a pointer to message context struct filled with the SOAP envelope to be sent

AXIS2_EXTERN axis2_msg_ctx_t* axis2_op_client_receive | ( | const axutil_env_t * | env,
|  | axis2_msg_ctx_t * | msg_ctx |
| ) |  |  |

Receives a message corresponding to a request depicted by given message context.

Parameters:

  | env | pointer to environment struct
  | msg_ctx | pointer to message context representing the response to be received

Returns:
  message context representing the received response

AXIS2_EXTERN axis2_status_t axis2_op_client_reset | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env |
| ) |  |  |

Resets the operation client to a clean status after the op has completed. This is how you can reuse an operation client. Note that this does not reset the options; only the internal state so the client can be used again.

Parameters:

  | op_client | pointer to operation client
  | env | pointer to environment struct

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_set_callback | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axis2_callback_t * | callback |
| ) |  |  |

Sets the callback to be executed when a response message is received.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct
  | callback | the callback to be used. operation client takes over the ownership of the message context struct.

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_set_callback_recv | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | struct axis2_callback_recv * | callback_recv |
| ) |  |  |

Sets callback receiver.

Parameters:

  | op_client | pointer to operation client struct
  | env | pointer to environment struct
  | callback_recv | pointer to callback receiver struct. operation client assumes ownership of the callback struct.

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_set_options | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | const axis2_options_t * | options |
| ) |  |  |

Sets the options that is to be used by this operation client.

Parameters:

  | op_client | pointer to operation 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 void axis2_op_client_set_reuse | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axis2_bool_t | reuse |
| ) |  |  |

Sets whether to reuse op client.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | reuse | flag is a boolean value

Returns:
  void

AXIS2_EXTERN axis2_status_t axis2_op_client_set_soap_action | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | axutil_string_t * | soap_action |
| ) |  |  |

Sets SOAP action.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | soap_action | SOAP action

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_set_soap_version_uri | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | const axis2_char_t * | soap_version_uri |
| ) |  |  |

Sets SOAP version URI.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | soap_version_uri | SOAP version URI

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_op_client_set_wsa_action | ( | axis2_op_client_t * | op_client,
|  | const axutil_env_t * | env,
|  | const axis2_char_t * | wsa_action |
| ) |  |  |

Sets WSA action.

Parameters:

  | op_client | pointer to op client struct
  | env | pointer to environment struct
  | wsa_action | Web services Addressing action

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_msg_ctx_t* axis2_op_client_two_way_send | ( | const axutil_env_t * | env,
|  | axis2_msg_ctx_t * | msg_ctx |
| ) |  |  |

Sends a message represented by the given message context and captures the response in return message context.

Parameters:

  | env | pointer to environment struct
  | msg_ctx | pointer to message context representing the message to be sent

Returns:
  message context representing the received response