# callback
[client API]

## Files
file | axis2_callback.h
## Typedefs
typedef struct axis2_callback | axis2_callback_t
typedef axis2_status_t | axis2_on_complete_func_ptr (axis2_callback_t *, const axutil_env_t *)
typedef axis2_status_t | axis2_on_error_func_ptr (axis2_callback_t *, const axutil_env_t *, int)
## Functions
AXIS2_EXTERN axis2_status_t | axis2_callback_invoke_on_complete (axis2_callback_t *callback, const axutil_env_t *env, axis2_async_result_t *result)
AXIS2_EXTERN axis2_status_t | axis2_callback_report_error (axis2_callback_t *callback, const axutil_env_t *env, const int exception)
AXIS2_EXTERN axis2_bool_t | axis2_callback_get_complete (const axis2_callback_t *callback, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_callback_set_complete (axis2_callback_t *callback, const axutil_env_t *env, const axis2_bool_t complete)
AXIS2_EXTERN axiom_soap_envelope_t * | axis2_callback_get_envelope (const axis2_callback_t *callback, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_callback_set_envelope (axis2_callback_t *callback, const axutil_env_t *env, axiom_soap_envelope_t *envelope)
AXIS2_EXTERN axis2_msg_ctx_t * | axis2_callback_get_msg_ctx (const axis2_callback_t *callback, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_callback_set_msg_ctx (axis2_callback_t *callback, const axutil_env_t *env, axis2_msg_ctx_t *msg_ctx)
AXIS2_EXTERN int | axis2_callback_get_error (const axis2_callback_t *callback, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_callback_set_error (axis2_callback_t *callback, const axutil_env_t *env, const int error)
AXIS2_EXTERN axis2_status_t | axis2_callback_set_data (axis2_callback_t *callback, void *data)
AXIS2_EXTERN void * | axis2_callback_get_data (const axis2_callback_t *callback)
AXIS2_EXTERN void | axis2_callback_set_on_complete (axis2_callback_t *callback, axis2_on_complete_func_ptr f)
AXIS2_EXTERN void | axis2_callback_set_on_error (axis2_callback_t *callback, axis2_on_error_func_ptr f)
AXIS2_EXTERN void | axis2_callback_free (axis2_callback_t *callback, const axutil_env_t *env)
AXIS2_EXTERN axis2_callback_t * | axis2_callback_create (const axutil_env_t *env)

## Detailed Description

callback represents the callback mechanisms to be used in case of asynchronous invocations. It holds the complete status of the invocation, the resulting SOAP envelope and also callback specific data. One can define a function to be called on complete of the callback as well as a function to be called on error.

## Typedef Documentation

typedef struct axis2_callback axis2_callback_t

Type name for axis2_callback

typedef axis2_status_t axis2_on_complete_func_ptr(axis2_callback_t *, const axutil_env_t *)

Type name for function pointer to be called on complete of callback

typedef axis2_status_t axis2_on_error_func_ptr(axis2_callback_t *, const axutil_env_t *, int)

Type name for function pointer to be called on error of callback

## Function Documentation

AXIS2_EXTERN axis2_callback_t* axis2_callback_create | ( | const axutil_env_t * | env | ) |

Creates a callback struct.

Parameters:

  | env | pointer to environment struct

Returns:
  pointer to newly created callback struct

AXIS2_EXTERN void axis2_callback_free | ( | axis2_callback_t * | callback,
|  | const axutil_env_t * | env |
| ) |  |  |

Frees callback struct.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_bool_t axis2_callback_get_complete | ( | const axis2_callback_t * | callback,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets the complete status for the callback. This method is useful for polling (busy waiting). e.g. ``

              while(!axis2_callback_get_complete(callback, env)
              {
                 sleep(10);
              }
     do whatever you need here

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct

Returns:
  AXIS2_TRUE if callback is complete, else AXIS2_FALSE

AXIS2_EXTERN void* axis2_callback_get_data | ( | const axis2_callback_t * | callback | ) |

Gets the callback data.

Parameters:

  | callback | pointer to callback struct

Returns:
  pointer to callback data

AXIS2_EXTERN axiom_soap_envelope_t* axis2_callback_get_envelope | ( | const axis2_callback_t * | callback,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets the resulting SOAP envelope.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct

Returns:
  result SOAP envelope if present, else NULL

AXIS2_EXTERN int axis2_callback_get_error | ( | const axis2_callback_t * | callback,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets error code representing the error.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct

Returns:
  error code representing the error

AXIS2_EXTERN axis2_msg_ctx_t* axis2_callback_get_msg_ctx | ( | const axis2_callback_t * | callback,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets the resulting message context.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct

Returns:
  result message context if present, else NULL

AXIS2_EXTERN axis2_status_t axis2_callback_invoke_on_complete | ( | axis2_callback_t * | callback,
|  | const axutil_env_t * | env,
|  | axis2_async_result_t * | result |
| ) |  |  |

This function is called once the asynchronous operation is successfully completed and the result is available.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct
  | result | pointer to async result

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_callback_report_error | ( | axis2_callback_t * | callback,
|  | const axutil_env_t * | env,
|  | const int | exception |
| ) |  |  |

This function is called once the asynchronous operation fails and the failure code returns.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct
  | exception | error code representing the error

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_callback_set_complete | ( | axis2_callback_t * | callback,
|  | const axutil_env_t * | env,
|  | const axis2_bool_t | complete |
| ) |  |  |

Sets the complete status.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct
  | complete | bool value representing the status

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_callback_set_data | ( | axis2_callback_t * | callback,
|  | void * | data |
| ) |  |  |

Sets the callback data.

Parameters:

  | callback | pointer to callback struct
  | data | pointer to data

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_callback_set_envelope | ( | axis2_callback_t * | callback,
|  | const axutil_env_t * | env,
|  | axiom_soap_envelope_t * | envelope |
| ) |  |  |

Sets the SOAP envelope.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct
  | envelope | pointer to SOAP envelope

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_callback_set_error | ( | axis2_callback_t * | callback,
|  | const axutil_env_t * | env,
|  | const int | error |
| ) |  |  |

Sets the error code.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct
  | error | error code representing the error

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_callback_set_msg_ctx | ( | axis2_callback_t * | callback,
|  | const axutil_env_t * | env,
|  | axis2_msg_ctx_t * | msg_ctx |
| ) |  |  |

Sets the message context.

Parameters:

  | callback | pointer to callback struct
  | env | pointer to environment struct
  | msg_ctx | pointer to message context

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN void axis2_callback_set_on_complete | ( | axis2_callback_t * | callback,
|  | axis2_on_complete_func_ptr | f |
| ) |  |  |

Sets the on complete callback function.

Parameters:

  | callback | pointer to callback struct
  | f | on complete callback function pointer

AXIS2_EXTERN void axis2_callback_set_on_error | ( | axis2_callback_t * | callback,
|  | axis2_on_error_func_ptr | f |
| ) |  |  |

Sets the on error callback function.

Parameters:

  | callback | pointer to callback struct
  | f | on error callback function pointer