Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:53 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 \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 /*! \brief Lookup the given number in the given dundi context (or e164 if unspecified) using the given callerid (if specified) and return up to maxret results in the array specified.
    00217    returns the number of results found or -1 on a hangup of teh channel. */
    00218 int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache);
    00219
    00220 /*! \brief Retrieve information on a specific EID */
    00221 int dundi_query_eid(struct dundi_entity_info *dei, const char *dcontext, dundi_eid eid);
    00222
    00223 /*! \brief Pre-cache to push upstream peers */
    00224 int dundi_precache(const char *dcontext, const char *number);
    00225
    00226 #endif /* _ASTERISK_DUNDI_H */