Thu Jul 9 13:40:33 2009

Asterisk developer's documentation


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

Generated on Thu Jul 9 13:40:33 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7