# handler

## Files
file | axis2_handler.h
## Typedefs
typedef struct axis2_handler | axis2_handler_t
typedef axis2_status_t(* | AXIS2_HANDLER_INVOKE )(axis2_handler_t *handler, const axutil_env_t *env, struct axis2_msg_ctx *msg_ctx)
typedef axis2_handler_t *(* | AXIS2_HANDLER_CREATE_FUNC )(const axutil_env_t *env, const axutil_string_t *name)
## Functions
AXIS2_EXTERN void | axis2_handler_free (axis2_handler_t *handler, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_handler_init (axis2_handler_t *handler, const axutil_env_t *env, struct axis2_handler_desc *handler_desc)
AXIS2_EXTERN axis2_status_t | axis2_handler_invoke (axis2_handler_t *handler, const axutil_env_t *env, struct axis2_msg_ctx *msg_ctx)
AXIS2_EXTERN const axutil_string_t * | axis2_handler_get_name (const axis2_handler_t *handler, const axutil_env_t *env)
AXIS2_EXTERN axutil_param_t * | axis2_handler_get_param (const axis2_handler_t *handler, const axutil_env_t *env, const axis2_char_t *name)
AXIS2_EXTERN struct axis2_handler_desc * | axis2_handler_get_handler_desc (const axis2_handler_t *handler, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_handler_set_invoke (axis2_handler_t *handler, const axutil_env_t *env, AXIS2_HANDLER_INVOKE func)
AXIS2_EXTERN axis2_handler_t * | axis2_handler_create (const axutil_env_t *env)
AXIS2_EXTERN axis2_handler_t * | axis2_ctx_handler_create (const axutil_env_t *env, const axutil_string_t *qname)

## Detailed Description

handler is the smallest unit of execution in the Axis2 engine's execution flow. The engine could have two flows, the in-flow and out-flow. A flow is a collection of phases and a phase in turn is a collection of handlers. handlers are configured in relation to modules. A module is a point of extension in the Axis2 engine and a module would have one or more handlers defined in its configuration. The module configuration defines the phases each handler is attached to. A handler is invoked when the phase within which it lives is invoked. handler is stateless and it is using the message context that the state information is captures across invocations.

## Typedef Documentation

typedef axis2_handler_t*( * AXIS2_HANDLER_CREATE_FUNC)(const axutil_env_t *env, const axutil_string_t *name)

Function pointer defining the creates syntax for a handler struct instance.

Parameters:

  | env | pointer to environment struct
  | pointer | to qname

Returns:
  pointer to newly created handler struct

typedef struct axis2_handler axis2_handler_t

Type name for struct axis2_handler

## Function Documentation

AXIS2_EXTERN axis2_handler_t* axis2_ctx_handler_create | ( | const axutil_env_t * | env,
|  | const axutil_string_t * | qname |
| ) |  |  |

Creates a handler with invoke method implemented to fill in the service and operation context information.

Parameters:

  | env | pointer to environment struct
  | qname | pointer to qname, this is cloned within create method

Returns:
  pointer to newly created handler struct

AXIS2_EXTERN axis2_handler_t* axis2_handler_create | ( | const axutil_env_t * | env | ) |

Creates handler struct instance.

Parameters:

  | env | pointer to environment struct

Returns:
  pointer to newly created handler struct

AXIS2_EXTERN void axis2_handler_free | ( | axis2_handler_t * | handler,
|  | const axutil_env_t * | env |
| ) |  |  |

Free handler struct.

Parameters:

  | handler | pointer to handler
  | env | pointer to environment struct

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN struct axis2_handler_desc* axis2_handler_get_handler_desc | ( | const axis2_handler_t * | handler,
|  | const axutil_env_t * | env |
| ) |  |  | `[read]`

Gets the handler description related to the handler.

Parameters:

  | handler | pointer to handler
  | env | pointer to environment struct

Returns:
  pointer to handler description struct related to handler

AXIS2_EXTERN const axutil_string_t* axis2_handler_get_name | ( | const axis2_handler_t * | handler,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets QName.

Parameters:

  | handler | pointer to handler
  | env | pointer to environment struct

Returns:
  pointer to QName of the handler

AXIS2_EXTERN axutil_param_t* axis2_handler_get_param | ( | const axis2_handler_t * | handler,
|  | const axutil_env_t * | env,
|  | const axis2_char_t * | name |
| ) |  |  |

Gets the named parameter.

Parameters:

  | handler | pointer to handler
  | env | pointer to environment struct
  | name | name of the parameter to be accessed

AXIS2_EXTERN axis2_status_t axis2_handler_init | ( | axis2_handler_t * | handler,
|  | const axutil_env_t * | env,
|  | struct axis2_handler_desc * | handler_desc |
| ) |  |  |

Initializes the handler with the information form handler description.

Parameters:

  | handler | pointer to handler
  | env | pointer to environment struct
  | handler_desc | pointer to handler description related to the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_handler_invoke | ( | axis2_handler_t * | handler,
|  | const axutil_env_t * | env,
|  | struct axis2_msg_ctx * | msg_ctx |
| ) |  |  |

Invoke is called to do the actual work assigned to the handler. The phase that owns the handler is responsible for calling invoke on top of the handler. Those structs that implement the interface of the handler should implement the logic for invoke and assign the respective function pointer to invoke operation of the ops struct.

Parameters:

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

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE