dundi.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 /*! \file
00020  * \brief Distributed Universal Number Discovery (DUNDi)
00021  * See also \arg \ref AstDUNDi
00022  */
00023 
00024 #ifndef _ASTERISK_DUNDI_H 
00025 #define _ASTERISK_DUNDI_H
00026 
00027 #include "asterisk/channel.h"
00028 #include "asterisk/utils.h"
00029 
00030 #define DUNDI_PORT 4520
00031 
00032 typedef struct ast_eid dundi_eid;
00033 
00034 struct dundi_hdr {
00035    unsigned short strans;        /*!< Source transaction */
00036    unsigned short dtrans;        /*!< Destination transaction */
00037    unsigned char iseqno;         /*!< Next expected incoming sequence number */
00038    unsigned char oseqno;         /*!< Outgoing sequence number */
00039    unsigned char cmdresp;        /*!< Command / Response */
00040    unsigned char cmdflags;       /*!< Command / Response specific flags*/
00041    unsigned char ies[0];
00042 } __attribute__((__packed__));
00043 
00044 struct dundi_ie_hdr {
00045    unsigned char ie;
00046    unsigned char len;
00047    unsigned char iedata[0];
00048 } __attribute__((__packed__));
00049 
00050 #define DUNDI_FLAG_RETRANS    (1 << 16)   /*!< Applies to dtrans */
00051 #define DUNDI_FLAG_RESERVED      (1 << 16)   /*!< Applies to strans */
00052 
00053 enum {
00054    /*! No answer yet */
00055    DUNDI_PROTO_NONE = 0,
00056    /*! IAX, version 2 */
00057    DUNDI_PROTO_IAX  = 1,
00058    /*! SIP - Session Initiation Protocol, RFC 3261 */
00059    DUNDI_PROTO_SIP  = 2,
00060    /*! ITU H.323 */
00061    DUNDI_PROTO_H323 = 3,
00062 };
00063 
00064 enum {
00065    /*! Isn't and can't be a valid number */
00066    DUNDI_FLAG_NONEXISTENT =    (0),
00067    /*! Is a valid number */
00068    DUNDI_FLAG_EXISTS =         (1 << 0),
00069    /*! Might be valid if you add more digits */
00070    DUNDI_FLAG_MATCHMORE =      (1 << 1),
00071    /*! Might be a match */
00072    DUNDI_FLAG_CANMATCH =       (1 << 2),
00073    /*! Keep dialtone */
00074    DUNDI_FLAG_IGNOREPAT =      (1 << 3),
00075    /*! Destination known to be residential */
00076    DUNDI_FLAG_RESIDENTIAL =    (1 << 4),
00077    /*! Destination known to be commercial */
00078    DUNDI_FLAG_COMMERCIAL =     (1 << 5),
00079    /*! Destination known to be cellular/mobile */
00080    DUNDI_FLAG_MOBILE =         (1 << 6),
00081    /*! No unsolicited calls of any kind through this route */
00082    DUNDI_FLAG_NOUNSOLICITED =  (1 << 7),
00083    /*! No commercial unsolicited calls through this route */
00084    DUNDI_FLAG_NOCOMUNSOLICIT = (1 << 8),
00085 };
00086 
00087 enum {
00088    DUNDI_HINT_NONE =        (0),
00089    /*! TTL Expired */
00090    DUNDI_HINT_TTL_EXPIRED = (1 << 0),
00091    /*! Don't ask for anything beginning with data */
00092    DUNDI_HINT_DONT_ASK =    (1 << 1),
00093    /*! Answer not affected by entity list */
00094    DUNDI_HINT_UNAFFECTED =  (1 << 2),
00095 };
00096 
00097 struct dundi_encblock {          /*!< AES-128 encrypted block */
00098    unsigned char iv[16];         /*!< Initialization vector of random data */
00099    unsigned char encdata[0];     /*!< Encrypted / compressed data */
00100 } __attribute__((__packed__));
00101 
00102 struct dundi_answer {
00103    dundi_eid eid;          /*!< Original source of answer */
00104    unsigned char protocol;       /*!< Protocol (DUNDI_PROTO_*) */
00105    unsigned short flags;         /*!< Flags relating to answer */
00106    unsigned short weight;        /*!< Weight of answers */
00107    unsigned char data[0];        /*!< Protocol specific URI */
00108 } __attribute__((__packed__));
00109 
00110 struct dundi_hint {
00111    unsigned short flags;         /*!< Flags relating to answer */
00112    unsigned char data[0];        /*!< For data for hint */
00113 } __attribute__((__packed__));
00114 
00115 enum {
00116    /*! Success */
00117    DUNDI_CAUSE_SUCCESS =     0,
00118    /*! General unspecified failure */
00119    DUNDI_CAUSE_GENERAL =     1,
00120    /*! Requested entity is dynamic */
00121    DUNDI_CAUSE_DYNAMIC =     2,
00122    /*! No or improper authorization */
00123    DUNDI_CAUSE_NOAUTH =      3,
00124    /*! Duplicate request */
00125    DUNDI_CAUSE_DUPLICATE =   4,
00126    /*! Expired TTL */
00127    DUNDI_CAUSE_TTL_EXPIRED = 5,
00128    /*! Need new session key to decode */
00129    DUNDI_CAUSE_NEEDKEY =     6,
00130    /*! Badly encrypted data */
00131    DUNDI_CAUSE_BADENCRYPT =  7,
00132 };
00133 
00134 struct dundi_cause {       
00135    unsigned char causecode;      /*!< Numerical cause (DUNDI_CAUSE_*) */
00136    char desc[0];           /*!< Textual description */
00137 } __attribute__((__packed__));
00138 
00139 struct dundi_peer_status {
00140    unsigned int flags;
00141    unsigned short netlag;
00142    unsigned short querylag;
00143    dundi_eid peereid;
00144 } __attribute__((__packed__));
00145 
00146 enum {
00147    DUNDI_PEER_PRIMARY =        (1 << 0),
00148    DUNDI_PEER_SECONDARY =      (1 << 1),
00149    DUNDI_PEER_UNAVAILABLE =    (1 << 2),
00150    DUNDI_PEER_REGISTERED =     (1 << 3),
00151    DUNDI_PEER_MOD_OUTBOUND =   (1 << 4),
00152    DUNDI_PEER_MOD_INBOUND =    (1 << 5),
00153    DUNDI_PEER_PCMOD_OUTBOUND = (1 << 6),
00154    DUNDI_PEER_PCMOD_INBOUND =  (1 << 7),
00155 };
00156 
00157 #define DUNDI_COMMAND_FINAL      (0x80)      /*!< Or'd with other flags */
00158 
00159 #define DUNDI_COMMAND_ACK     (0 | 0x40)  /*!< Ack a message */
00160 #define DUNDI_COMMAND_DPDISCOVER 1     /*!< Request discovery */
00161 #define DUNDI_COMMAND_DPRESPONSE (2 | 0x40)  /*!< Respond to a discovery request */
00162 #define DUNDI_COMMAND_EIDQUERY      3     /*!< Request information for a peer */
00163 #define DUNDI_COMMAND_EIDRESPONSE   (4 | 0x40)  /*!< Response to a peer query */
00164 #define DUNDI_COMMAND_PRECACHERQ 5     /*!< Pre-cache Request */
00165 #define DUNDI_COMMAND_PRECACHERP (6 | 0x40)  /*!< Pre-cache Response */
00166 #define DUNDI_COMMAND_INVALID    (7 | 0x40)  /*!< Invalid dialog state (does not require ack) */
00167 #define DUNDI_COMMAND_UNKNOWN    (8 | 0x40)  /*!< Unknown command */
00168 #define DUNDI_COMMAND_NULL    9     /*!< No-op */
00169 #define DUNDI_COMMAND_REGREQ     (10)     /*!< Register Request */
00170 #define DUNDI_COMMAND_REGRESPONSE   (11 | 0x40) /*!< Register Response */
00171 #define DUNDI_COMMAND_CANCEL     (12)     /*!< Cancel transaction entirely */
00172 #define DUNDI_COMMAND_ENCRYPT    (13)     /*!< Send an encrypted message */
00173 #define DUNDI_COMMAND_ENCREJ     (14 | 0x40) /*!< Reject an encrypted message */
00174 
00175 #define DUNDI_COMMAND_STATUS     15    /*!< Status command */
00176 
00177 /*
00178  * Remember that some information elements may occur
00179  * more than one time within a message
00180  */
00181 
00182 #define DUNDI_IE_EID       1  /*!< Entity identifier (dundi_eid) */
00183 #define DUNDI_IE_CALLED_CONTEXT     2  /*!< DUNDi Context (string) */
00184 #define DUNDI_IE_CALLED_NUMBER      3  /*!< Number of equivalent (string) */
00185 #define DUNDI_IE_EID_DIRECT      4  /*!< Entity identifier (dundi_eid), direct connect */
00186 #define DUNDI_IE_ANSWER       5  /*!< An answer (struct dundi_answer) */
00187 #define DUNDI_IE_TTL       6  /*!< Max TTL for this request / Remaining TTL for the response  (short)*/
00188 #define DUNDI_IE_VERSION      10 /*!< DUNDi version (should be 1) (short) */
00189 #define DUNDI_IE_EXPIRATION      11 /*!< Recommended expiration (short) */
00190 #define DUNDI_IE_UNKNOWN      12 /*!< Unknown command (byte) */
00191 #define DUNDI_IE_CAUSE        14 /*!< Success or cause of failure */
00192 #define DUNDI_IE_REQEID       15 /*!< EID being requested for EIDQUERY*/
00193 #define DUNDI_IE_ENCDATA      16 /*!< AES-128 encrypted data */
00194 #define DUNDI_IE_SHAREDKEY    17 /*!< RSA encrypted AES-128 key */
00195 #define DUNDI_IE_SIGNATURE    18 /*!< RSA Signature of encrypted shared key */
00196 #define DUNDI_IE_KEYCRC32     19 /*!< CRC32 of encrypted key (int) */
00197 #define DUNDI_IE_HINT         20 /*!< Answer hints */
00198 
00199 #define DUNDI_IE_DEPARTMENT      21 /*!< Department, for EIDQUERY (string) */
00200 #define DUNDI_IE_ORGANIZATION    22 /*!< Organization, for EIDQUERY (string) */
00201 #define DUNDI_IE_LOCALITY     23 /*!< City/Locality, for EIDQUERY (string) */
00202 #define DUNDI_IE_STATE_PROV      24 /*!< State/Province, for EIDQUERY (string) */
00203 #define DUNDI_IE_COUNTRY      25 /*!< Country, for EIDQUERY (string) */
00204 #define DUNDI_IE_EMAIL        26 /*!< E-mail addy, for EIDQUERY (string) */
00205 #define DUNDI_IE_PHONE        27 /*!< Contact Phone, for EIDQUERY (string) */
00206 #define DUNDI_IE_IPADDR       28 /*!< IP Address, for EIDQUERY (string) */
00207 #define DUNDI_IE_CACHEBYPASS     29 /*!< Bypass cache (empty) */
00208 
00209 #define DUNDI_IE_PEERSTATUS      30    /*!< Peer/peer status (struct dundi_peer_status) */
00210 
00211 #define DUNDI_FLUFF_TIME      2000  /*!< Amount of time for answer */
00212 #define DUNDI_TTL_TIME        200   /*!< Incremental average time */
00213 
00214 #define DUNDI_DEFAULT_RETRANS    5
00215 #define DUNDI_DEFAULT_RETRANS_TIMER 1000
00216 #define DUNDI_DEFAULT_TTL     120   /*!< In seconds/hops like TTL */
00217 #define DUNDI_DEFAULT_VERSION    1
00218 #define DUNDI_DEFAULT_CACHE_TIME 3600  /*!< In seconds */
00219 #define DUNDI_DEFAULT_KEY_EXPIRE 3600  /*!< Life of shared key In seconds */
00220 #define DUNDI_DEF_EMPTY_CACHE_TIME  60 /*!< In seconds, cache of empty answer */
00221 #define DUNDI_WINDOW       1  /*!< Max 1 message in window */
00222 
00223 #define DEFAULT_MAXMS         2000
00224 
00225 struct dundi_result {
00226    unsigned int flags;
00227    int weight;
00228    int expiration;
00229    int techint;
00230    dundi_eid eid;
00231    char eid_str[20];
00232    char tech[10];
00233    char dest[256];
00234 };
00235 
00236 struct dundi_entity_info {
00237    char country[80];
00238    char stateprov[80];
00239    char locality[80];
00240    char org[80];
00241    char orgunit[80];
00242    char email[80];
00243    char phone[80];   
00244    char ipaddr[80];
00245 };
00246 
00247 /*! 
00248  * \brief Lookup the given number in the given dundi context.
00249  * Lookup number in a given dundi context (if unspecified use e164), the given callerid (if specified) 
00250  * and return up to maxret results in the array specified.
00251  * \retval the number of results found.
00252  * \retval -1 on a hangup of the channel. 
00253 */
00254 int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache);
00255 
00256 /*! \brief Retrieve information on a specific EID */
00257 int dundi_query_eid(struct dundi_entity_info *dei, const char *dcontext, dundi_eid eid);
00258 
00259 /*! \brief Pre-cache to push upstream peers */
00260 int dundi_precache(const char *dcontext, const char *number);
00261 
00262 #endif /* _ASTERISK_DUNDI_H */

Generated on Thu Apr 16 06:27:33 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6