$Revision$
$Date$

# Structure module_exports

This structure describes interface that must be exported by each module. Every module must have a global variable named `exports` which is of type struct module_exports.

Immediately after `dlopen` the server will try to find symbol named `exports` in the module to be loaded. This symbol is a structure describing interface of the module. Pointer to the symbol will be then put in exports field of sr_module structure representing the module in the server.

Detailed description of the structure follows:

    struct module_exports{
        char* name;                     /* null terminated module name */
        char** cmd_names;               /* cmd names registered
                                         * by this module */
        cmd_function* cmd_pointers;     /* pointers to the
                                         * corresponding functions */
        int* param_no;                  /* number of parameters used by
                                         * the function */
        fixup_function* fixup_pointers; /* pointers to functions
                                         * called to "fix"
                                         * the params, e.g: precompile
                                         * a re */
        int cmd_no;                     /* number of registered commands
                                         * (size of cmd_{names,pointers}
                                         */
        char** param_names;      /* parameter names registered
                                  * by this module */
        modparam_t* param_types; /* Type of parameters */
        void** param_pointers;   /* Pointers to the corresponding
                                  * memory locations */
        int par_no;              /* number of registered parameters */
        init_function init_f;         /* Initialization function */
        response_function response_f; /* function used for responses,
                                       * returns yes or no; can be null
                                       */
        destroy_function destroy_f;   /* function called when the module
                                       * should be "destroyed", e.g: on
                                       * ser exit;
                                       * can be null */
        onbreak_function onbreak_f;
        child_init_function init_child_f;  /* function called by all
                                            * processes after the fork */
    };

Fields and their description:

- name - Name of the module.

- cmd_names - Array of names of exported commands.

- cmd_pointers - Array of pointers to functions implementing commands specified in cmd_names array.

  Function Prototype:

      		    int cmd_function
      		    struct sip_msg* msg
      		    char* param1
      		    char* param2

  The first parameter is sip_msg currently being processed. Remaining parameters are parameters from the config file. If the function accepts only one parameter, `param2` will be set to zero, if the function accepts no parameters, `param1` and `param2` will be set to zero.

  The function should return number > 0 if everything went OK and processing of the message should continue. The function should return 0 if processing of the message should be stopped. The function should return number < 0 on an error.

- param_no - Array of number of parameters of exported commands.

- fixup_pointer - Array of pointers to fixup functions, each fixup function for one exported command. If there is no fixup function for a particular exported function, corresponding field in the array will contain zero.

  Function Prototype:

      		    int fixup_function
      		    void** param
      		    int param_no

  The first parameter is pointing to variable to be fixed. The second parameter is order of the variable.

  The function should return 0 if everything went OK and number < 0 on an error.

- cmd_no - Number of exported commands.

  cmd_names, cmd_pointers, param_no and fixup_pointer arrays must have at least cmd_no elements ! (It might even kill your cat if you fail to fulfill this condition).

- param_names - Array of names of exported parameters.

- param_types - Array of types of parameters, each field of the array can be either PARAM_STR/PARAM_STRING or PARAM_INT (currently only three parameter types are defined).

- param_pointers - Array of pointers to variables, that hold values of the parameters.

- param_no - Number of exported parameters.

  param_names, param_types and param_pointers arrays must have at least param_no elements ! (Remember the previous note about your cat ? The same might happen to your dog if you fail to fulfill the condition second time !).

- init_f - Pointer to module's initialization function, 0 if the module doesn't need initialization function.

  Function Prototype:

      		    int init_function

  The function should return 0 if everything went OK and number < 0 on an error;

- response_f - If a module is interested in seeing responses, it will provide pointer to a function here. The function will be called when a response comes. The field will contain 0 if the module doesn't want to see responses.

  Function Prototype:

      		    int response_function
      		    struct sip_msg* msg

  The function accepts one parameter which is structure representing the response currently being processed.

  The function should return 0 if the response should be dropped.

- destroy_f - Destroy function. The function will be called when the server is shutting down. Can be 0 if the module doesn't need destroy function.

  Function Prototype:

      		    void destroy_function

- onbreak_f - On break function. The function will be called when processing of a route statement was aborted. Can be 0 if module doesn't need this function.

  Function Prototype:

      		    void onbreak_function
      		    struct sip_msg* msg

  The function accepts one parameter which is message currently being processed.

- init_child_f - Child initialization function. This is an additional initialization function. init_f will be called from the main process BEFORE the main process forks children. init_child_f will be called from all children AFTER the fork.

  Per-child specific initialization can be done here. For example, each child can open its own database connection in the function, and so on.

  Function Prototype:

      		    int child_init_function
      		    int rank

  The function accepts one parameter, which is rank (starting from 0) of child executing the function.

  The function should return 0 if everything went OK and number < 0 on an error.