Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:54 2009

## Asterisk developer's documentation

# manager.h

Go to the documentation of this file.

    00001 /*
    00002  * Asterisk -- An open source telephony toolkit.
    00003  *
    00004  * Copyright (C) 1999 - 2005, Digium, Inc.
    00005  *
    00006  * Mark Spencer <markster@digium.com>
    00007  *
    00008  * See http://www.asterisk.org for more information about
    00009  * the Asterisk project. Please do not directly contact
    00010  * any of the maintainers of this project for assistance;
    00011  * the project provides a web site, mailing lists and IRC
    00012  * channels for your use.
    00013  *
    00014  * This program is free software, distributed under the terms of
    00015  * the GNU General Public License Version 2. See the LICENSE file
    00016  * at the top of the source tree.
    00017  */
    00018
    00019 #ifndef _ASTERISK_MANAGER_H
    00020 #define _ASTERISK_MANAGER_H
    00021
    00022 #include <stdarg.h>
    00023 #include <sys/types.h>
    00024 #include <sys/socket.h>
    00025 #include <netinet/in.h>
    00026 #include <arpa/inet.h>
    00027
    00028 #include "asterisk/lock.h"
    00029
    00030 /*!
    00031  \file
    00032  \brief The AMI - Asterisk Manager Interface - is a TCP protocol created to
    00033  manage Asterisk with third-party software.
    00034
    00035  Manager protocol packages are text fields of the form a: b.  There is
    00036  always exactly one space after the colon.
    00037
    00038  The first header type is the "Event" header.  Other headers vary from
    00039  event to event.  Headers end with standard \r\n termination.
    00040  The last line of the manager response or event is an empty line.
    00041  (\r\n)
    00042
    00043  ** Please try to re-use existing headers to simplify manager message parsing in clients.
    00044     Don't re-use an existing header with a new meaning, please.
    00045     You can find a reference of standard headers in doc/manager.txt
    00046  */
    00047
    00048 #define DEFAULT_MANAGER_PORT 5038   /* Default port for Asterisk management via TCP */
    00049
    00050 #define EVENT_FLAG_SYSTEM     (1 << 0) /* System events such as module load/unload */
    00051 #define EVENT_FLAG_CALL       (1 << 1) /* Call event, such as state change, etc */
    00052 #define EVENT_FLAG_LOG        (1 << 2) /* Log events */
    00053 #define EVENT_FLAG_VERBOSE    (1 << 3) /* Verbose messages */
    00054 #define EVENT_FLAG_COMMAND    (1 << 4) /* Ability to read/set commands */
    00055 #define EVENT_FLAG_AGENT      (1 << 5) /* Ability to read/set agent info */
    00056 #define EVENT_FLAG_USER                 (1 << 6) /* Ability to read/set user info */
    00057
    00058 /* Export manager structures */
    00059 #define AST_MAX_MANHEADERS 80
    00060 #define AST_MAX_MANHEADER_LEN 256
    00061
    00062 struct eventqent {
    00063    struct eventqent *next;
    00064    char eventdata[1];
    00065 };
    00066
    00067 struct mansession {
    00068    /*! Execution thread */
    00069    pthread_t t;
    00070    /*! Thread lock -- don't use in action callbacks, it's already taken care of  */
    00071    ast_mutex_t __lock;
    00072    /*! socket address */
    00073    struct sockaddr_in sin;
    00074    /*! TCP socket */
    00075    int fd;
    00076    /*! Whether or not we're busy doing an action */
    00077    int busy;
    00078    /*! Whether or not we're "dead" */
    00079    int dead;
    00080    /*! Logged in username */
    00081    char username[80];
    00082    /*! Authentication challenge */
    00083    char challenge[10];
    00084    /*! Authentication status */
    00085    int authenticated;
    00086    /*! Authorization for reading */
    00087    int readperm;
    00088    /*! Authorization for writing */
    00089    int writeperm;
    00090    /*! Buffer */
    00091    char inbuf[AST_MAX_MANHEADER_LEN];
    00092    int inlen;
    00093    int send_events;
    00094    /* Queued events that we've not had the ability to send yet */
    00095    struct eventqent *eventq;
    00096    /* Timeout for ast_carefulwrite() */
    00097    int writetimeout;
    00098    struct mansession *next;
    00099 };
    00100
    00101
    00102 struct message {
    00103    int hdrcount;
    00104    char headers[AST_MAX_MANHEADERS][AST_MAX_MANHEADER_LEN];
    00105 };
    00106
    00107 struct manager_action {
    00108    /*! Name of the action */
    00109    const char *action;
    00110    /*! Short description of the action */
    00111    const char *synopsis;
    00112    /*! Detailed description of the action */
    00113    const char *description;
    00114    /*! Permission required for action.  EVENT_FLAG_* */
    00115    int authority;
    00116    /*! Function to be called */
    00117    int (*func)(struct mansession *s, struct message *m);
    00118    /*! For easy linking */
    00119    struct manager_action *next;
    00120 };
    00121
    00122 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
    00123
    00124 /* External routines may register/unregister manager callbacks this way */
    00125 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
    00126
    00127 /* Use ast_manager_register2 to register with help text for new manager commands */
    00128
    00129 /*! Register a manager command with the manager interface */
    00130 /*!   \param action Name of the requested Action:
    00131    \param authority Required authority for this command
    00132    \param func Function to call for this command
    00133    \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
    00134    \param description Help text, several lines
    00135 */
    00136 int ast_manager_register2(
    00137    const char *action,
    00138    int authority,
    00139    int (*func)(struct mansession *s, struct message *m),
    00140    const char *synopsis,
    00141    const char *description);
    00142
    00143 /*! Unregister a registred manager command */
    00144 /*!   \param action Name of registred Action:
    00145 */
    00146 int ast_manager_unregister( char *action );
    00147
    00148 /*! External routines may send asterisk manager events this way */
    00149 /*!   \param category   Event category, matches manager authorization
    00150    \param event   Event name
    00151    \param contents   Contents of event
    00152 */
    00153 extern int manager_event(int category, char *event, char *contents, ...)
    00154    __attribute__ ((format (printf, 3,4)));
    00155
    00156 /*! Get header from mananger transaction */
    00157 extern char *astman_get_header(struct message *m, char *var);
    00158
    00159 /*! Get a linked list of the Variable: headers */
    00160 struct ast_variable *astman_get_variables(struct message *m);
    00161
    00162 /*! Send error in manager transaction */
    00163 extern void astman_send_error(struct mansession *s, struct message *m, char *error);
    00164 extern void astman_send_response(struct mansession *s, struct message *m, char *resp, char *msg);
    00165 extern void astman_send_ack(struct mansession *s, struct message *m, char *msg);
    00166
    00167 /*! Called by Asterisk initialization */
    00168 extern int init_manager(void);
    00169 /*! Called by Asterisk initialization */
    00170 extern int reload_manager(void);
    00171
    00172 #endif /* _ASTERISK_MANAGER_H */