ProFTPD Developer's Guide: Controls API Functions

ProFTPD Version 1.2

Controls API Functions

  int pr_ctrls_register(module *module, const char *action,
    int (*ctrls_cb)(pr_ctrls_t *, int, char **));
  int pr_ctrls_unregister(module *module, const char *action);
  int pr_ctrls_add_arg(pr_ctrls_t *ctrl, char *ctrls_arg);
  int pr_ctrls_add_response(pr_ctrls_t *ctrl, char *fmt, ...);
  int pr_ctrls_connect(void);
  int pr_ctrls_copy_args(pr_ctrls_t *src_ctrl, pr_ctrls_t *dest_ctrl);
  int pr_ctrls_copy_resps(pr_ctrls_t *src_ctrl, pr_ctrls_t *dest_ctrl);
  int pr_ctrls_flush_response(pr_ctrls_t *ctrl);
  int pr_ctrls_parse_msg(pool *msg_pool, char *msg, unsigned int *msgargc, char ***msgargv);
  int pr_ctrls_recv_request(pr_ctrls_cl_t *cl);
  int pr_ctrls_recv_response(pool *resp_pool, int ctrls_sockfd, int *status, char ***respargv); 
  int pr_ctrls_send_msg(int sockfd, int msgstatus, unsigned int msgargc, char **msgargv);
  void pr_block_ctrls(void);
  void pr_unblock_ctrls(void);
  int pr_check_ctrls(void);
  int pr_run_ctrls(module *module, const char *action);
  void pr_clear_ctrls();
  void pr_init_ctrls();

The pr_ctrls_register() function will be used by modules to register custom control handlers with the Controls layer. The registration consists of a pointer to the registering module module, the action by which clients can request this control to be run, and a callback function pointer to the control's handler. The control handler must return an integer status value (preferably conforming to the norm of 0 indicating success, -1 indicating an error), and must take three arguments: a pointer to the registered pr_ctrls_t object, and integer number of request strings, and an array of the indicated number of request strings (similar to the argc, argv of most programs' main() function). This function will return the ID of the registered pr_ctrls_t control object if successful, or -1 if an error occurred during registration.

The pr_ctrls_unregister() function unregisters any registered control handlers that match the given module and action arguments. module may be ANY_MODULE, meaning that control handlers from all modules should be searched. action may not be NULL, else this function will return -1 with errno set to EINVAL. If no matching control handlers were found, a -1 will be returned with errno set to EPERM. A return value of 0 means the requested controls were successfully unregistered from the Controls layer.

The pr_ctrls_add_arg() function is a utility function used to add the given ctrls_arg string to the control object's handler argument array. It will return 0 on success, -1 on failure. Most module code should not need to use this function.

The pr_ctrls_add_response() function is used by control handlers to add a text response string to the object that will eventually be returned to the requesting client. This function will return 0 if the response was succesfully added, or -1 if there was a problem.

The pr_ctrls_connect() function is to be used by client programs that wish to make control requests; this includes ftpdctl and any core or module routines wishing to submit programmatic requests. It connects to the well-defined Unix domain socket and returns the opened socket descriptor for use by the client, or -1 if there was an error, with errno set appropriately.

The pr_ctrls_copy_args() function is a utility function used to duplicate src_ctrl's handler argument array and place that duplicate in dest_ctrl. Control handlers should not need to use this function.

The pr_ctrls_copy_resps() function is a utility function used to make a duplicate of src_ctrl's handler response array for dest_ctrl. Control handlers should not need to use this function.

The pr_ctrls_flush_response() function flushes any responses of the given ctrl out to the client. Note that this function should be used rarely, and only when the control handler will not be returning normally (as when exiting the process). If ctrl is NULL, it will return -1 with errno set to EINVAL; an errno of EPERM means that the function was unable to flush the response to the client. A value of 0 is returned if the flush was successful.

The pr_ctrls_parse_msg() function parses the given msg into the provided msgargc, msgargv pointers, splitting the msg on whitespace (honoring quoting and escapes). The msgargv array of strings is allocated from msg_pool. This is provided as a utility function to modules, so that they may prepare a single string for use by pr_ctrls_send_msg(). A value of 0 is returned if successful, -1 if an error occurred.

The pr_ctrls_recv_request() function reads in a client's control request. It will return -1 with errno set to EOF if there was nothing to be read from the client socket; errno may have other values as appropriate for read(2) errors. A value of 0 will be returned if the request was successfully read.

The pr_ctrls_recv_response() function reads the control handler response from the given socket ctrls_sockfd, allocating memory for the strings from resp_pool. The return value of the control handler will be stored in status, and the array of response strings in respargv, if not NULL. respargv may indeed be NULL, as when the client does not really care about the responses and simply wants the status or to know that the response was successfully received. This function returns the number of responses received, or -1 with errno set properly if there was an error.

The pr_ctrls_send_msg() function is used to send both requests and responses. It sends msgargc number of strings, found in msgargv, to the socket sockfd. For requests, msgstatus is largely ignored; for responses, it contains the return value of the control handlers that handled the request.

The pr_block_ctrls() function blocks control handlers from being run. This is usually done when the control handler list is being modified, and should not be used by modules.

The pr_unblock_ctrls() function restores the control handler list to useable status, signalling that the state of the list is once more stable. This should not be used by modules.

The pr_check_ctrls() function is used to do a sanity check of the register control handlers. Some control handlers allow of only a single instance to handle a requested action, some allow multiple handlers for a requested action. Note: not currently implemented.

The pr_run_ctrls() function iterates through the list of registered pr_ctrls_t objects and invokes the callback handler functions of any that match the given module and action arguments. Returns 0 if successful, or -1 if there was a problem (as when controls are blocked). Modules and control handlers should not need to make use of this function.

The pr_clear_ctrls() function removes the control objects from the list that were registered in response to client requests, clearing the list for new client requests.

The pr_init_ctrls() function initializes the Controls layer.