incorporates r159808 from branches/1.4:
[asterisk/asterisk.git] / include / asterisk / dundi.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Distributed Universal Number Discovery (DUNDi)
21  * See also \arg \ref AstDUNDi
22  */
23
24 #ifndef _ASTERISK_DUNDI_H 
25 #define _ASTERISK_DUNDI_H
26
27 #include "asterisk/channel.h"
28 #include "asterisk/utils.h"
29
30 #define DUNDI_PORT 4520
31
32 typedef struct ast_eid dundi_eid;
33
34 struct dundi_hdr {
35         unsigned short strans;                  /*!< Source transaction */
36         unsigned short dtrans;                  /*!< Destination transaction */
37         unsigned char iseqno;                   /*!< Next expected incoming sequence number */
38         unsigned char oseqno;                   /*!< Outgoing sequence number */
39         unsigned char cmdresp;                  /*!< Command / Response */
40         unsigned char cmdflags;                 /*!< Command / Response specific flags*/
41         unsigned char ies[0];
42 } __attribute__((__packed__));
43
44 struct dundi_ie_hdr {
45         unsigned char ie;
46         unsigned char len;
47         unsigned char iedata[0];
48 } __attribute__((__packed__));
49
50 #define DUNDI_FLAG_RETRANS              (1 << 16)       /*!< Applies to dtrans */
51 #define DUNDI_FLAG_RESERVED             (1 << 16)       /*!< Applies to strans */
52
53 enum {
54         /*! No answer yet */
55         DUNDI_PROTO_NONE = 0,
56         /*! IAX, version 2 */
57         DUNDI_PROTO_IAX  = 1,
58         /*! SIP - Session Initiation Protocol, RFC 3261 */
59         DUNDI_PROTO_SIP  = 2,
60         /*! ITU H.323 */
61         DUNDI_PROTO_H323 = 3,
62 };
63
64 enum {
65         /*! Isn't and can't be a valid number */
66         DUNDI_FLAG_NONEXISTENT =    (0),
67         /*! Is a valid number */
68         DUNDI_FLAG_EXISTS =         (1 << 0),
69         /*! Might be valid if you add more digits */
70         DUNDI_FLAG_MATCHMORE =      (1 << 1),
71         /*! Might be a match */
72         DUNDI_FLAG_CANMATCH =       (1 << 2),
73         /*! Keep dialtone */
74         DUNDI_FLAG_IGNOREPAT =      (1 << 3),
75         /*! Destination known to be residential */
76         DUNDI_FLAG_RESIDENTIAL =    (1 << 4),
77         /*! Destination known to be commercial */
78         DUNDI_FLAG_COMMERCIAL =     (1 << 5),
79         /*! Destination known to be cellular/mobile */
80         DUNDI_FLAG_MOBILE =         (1 << 6),
81         /*! No unsolicited calls of any kind through this route */
82         DUNDI_FLAG_NOUNSOLICITED =  (1 << 7),
83         /*! No commercial unsolicited calls through this route */
84         DUNDI_FLAG_NOCOMUNSOLICIT = (1 << 8),
85 };
86
87 enum {
88         DUNDI_HINT_NONE =        (0),
89         /*! TTL Expired */
90         DUNDI_HINT_TTL_EXPIRED = (1 << 0),
91         /*! Don't ask for anything beginning with data */
92         DUNDI_HINT_DONT_ASK =    (1 << 1),
93         /*! Answer not affected by entity list */
94         DUNDI_HINT_UNAFFECTED =  (1 << 2),
95 };
96
97 struct dundi_encblock {                         /*!< AES-128 encrypted block */
98         unsigned char iv[16];                   /*!< Initialization vector of random data */
99         unsigned char encdata[0];               /*!< Encrypted / compressed data */
100 } __attribute__((__packed__));
101
102 struct dundi_answer {
103         dundi_eid eid;                          /*!< Original source of answer */
104         unsigned char protocol;                 /*!< Protocol (DUNDI_PROTO_*) */
105         unsigned short flags;                   /*!< Flags relating to answer */
106         unsigned short weight;                  /*!< Weight of answers */
107         unsigned char data[0];                  /*!< Protocol specific URI */
108 } __attribute__((__packed__));
109
110 struct dundi_hint {
111         unsigned short flags;                   /*!< Flags relating to answer */
112         unsigned char data[0];                  /*!< For data for hint */
113 } __attribute__((__packed__));
114
115 enum {
116         /*! Success */
117         DUNDI_CAUSE_SUCCESS =     0,
118         /*! General unspecified failure */
119         DUNDI_CAUSE_GENERAL =     1,
120         /*! Requested entity is dynamic */
121         DUNDI_CAUSE_DYNAMIC =     2,
122         /*! No or improper authorization */
123         DUNDI_CAUSE_NOAUTH =      3,
124         /*! Duplicate request */
125         DUNDI_CAUSE_DUPLICATE =   4,
126         /*! Expired TTL */
127         DUNDI_CAUSE_TTL_EXPIRED = 5,
128         /*! Need new session key to decode */
129         DUNDI_CAUSE_NEEDKEY =     6,
130         /*! Badly encrypted data */
131         DUNDI_CAUSE_BADENCRYPT =  7,
132 };
133
134 struct dundi_cause {                    
135         unsigned char causecode;                /*!< Numerical cause (DUNDI_CAUSE_*) */
136         char desc[0];                           /*!< Textual description */
137 } __attribute__((__packed__));
138
139 struct dundi_peer_status {
140         unsigned int flags;
141         unsigned short netlag;
142         unsigned short querylag;
143         dundi_eid peereid;
144 } __attribute__((__packed__));
145
146 enum {
147         DUNDI_PEER_PRIMARY =        (1 << 0),
148         DUNDI_PEER_SECONDARY =      (1 << 1),
149         DUNDI_PEER_UNAVAILABLE =    (1 << 2),
150         DUNDI_PEER_REGISTERED =     (1 << 3),
151         DUNDI_PEER_MOD_OUTBOUND =   (1 << 4),
152         DUNDI_PEER_MOD_INBOUND =    (1 << 5),
153         DUNDI_PEER_PCMOD_OUTBOUND = (1 << 6),
154         DUNDI_PEER_PCMOD_INBOUND =  (1 << 7),
155 };
156
157 #define DUNDI_COMMAND_FINAL             (0x80)          /*!< Or'd with other flags */
158
159 #define DUNDI_COMMAND_ACK               (0 | 0x40)      /*!< Ack a message */
160 #define DUNDI_COMMAND_DPDISCOVER        1               /*!< Request discovery */
161 #define DUNDI_COMMAND_DPRESPONSE        (2 | 0x40)      /*!< Respond to a discovery request */
162 #define DUNDI_COMMAND_EIDQUERY          3               /*!< Request information for a peer */
163 #define DUNDI_COMMAND_EIDRESPONSE       (4 | 0x40)      /*!< Response to a peer query */
164 #define DUNDI_COMMAND_PRECACHERQ        5               /*!< Pre-cache Request */
165 #define DUNDI_COMMAND_PRECACHERP        (6 | 0x40)      /*!< Pre-cache Response */
166 #define DUNDI_COMMAND_INVALID           (7 | 0x40)      /*!< Invalid dialog state (does not require ack) */
167 #define DUNDI_COMMAND_UNKNOWN           (8 | 0x40)      /*!< Unknown command */
168 #define DUNDI_COMMAND_NULL              9               /*!< No-op */
169 #define DUNDI_COMMAND_REGREQ            (10)            /*!< Register Request */
170 #define DUNDI_COMMAND_REGRESPONSE       (11 | 0x40)     /*!< Register Response */
171 #define DUNDI_COMMAND_CANCEL            (12)            /*!< Cancel transaction entirely */
172 #define DUNDI_COMMAND_ENCRYPT           (13)            /*!< Send an encrypted message */
173 #define DUNDI_COMMAND_ENCREJ            (14 | 0x40)     /*!< Reject an encrypted message */
174
175 #define DUNDI_COMMAND_STATUS            15              /*!< Status command */
176
177 /*
178  * Remember that some information elements may occur
179  * more than one time within a message
180  */
181
182 #define DUNDI_IE_EID                    1       /*!< Entity identifier (dundi_eid) */
183 #define DUNDI_IE_CALLED_CONTEXT         2       /*!< DUNDi Context (string) */
184 #define DUNDI_IE_CALLED_NUMBER          3       /*!< Number of equivalent (string) */
185 #define DUNDI_IE_EID_DIRECT             4       /*!< Entity identifier (dundi_eid), direct connect */
186 #define DUNDI_IE_ANSWER                 5       /*!< An answer (struct dundi_answer) */
187 #define DUNDI_IE_TTL                    6       /*!< Max TTL for this request / Remaining TTL for the response  (short)*/
188 #define DUNDI_IE_VERSION                10      /*!< DUNDi version (should be 1) (short) */
189 #define DUNDI_IE_EXPIRATION             11      /*!< Recommended expiration (short) */
190 #define DUNDI_IE_UNKNOWN                12      /*!< Unknown command (byte) */
191 #define DUNDI_IE_CAUSE                  14      /*!< Success or cause of failure */
192 #define DUNDI_IE_REQEID                 15      /*!< EID being requested for EIDQUERY*/
193 #define DUNDI_IE_ENCDATA                16      /*!< AES-128 encrypted data */
194 #define DUNDI_IE_SHAREDKEY              17      /*!< RSA encrypted AES-128 key */
195 #define DUNDI_IE_SIGNATURE              18      /*!< RSA Signature of encrypted shared key */
196 #define DUNDI_IE_KEYCRC32               19      /*!< CRC32 of encrypted key (int) */
197 #define DUNDI_IE_HINT                   20      /*!< Answer hints */
198
199 #define DUNDI_IE_DEPARTMENT             21      /*!< Department, for EIDQUERY (string) */
200 #define DUNDI_IE_ORGANIZATION           22      /*!< Organization, for EIDQUERY (string) */
201 #define DUNDI_IE_LOCALITY               23      /*!< City/Locality, for EIDQUERY (string) */
202 #define DUNDI_IE_STATE_PROV             24      /*!< State/Province, for EIDQUERY (string) */
203 #define DUNDI_IE_COUNTRY                25      /*!< Country, for EIDQUERY (string) */
204 #define DUNDI_IE_EMAIL                  26      /*!< E-mail addy, for EIDQUERY (string) */
205 #define DUNDI_IE_PHONE                  27      /*!< Contact Phone, for EIDQUERY (string) */
206 #define DUNDI_IE_IPADDR                 28      /*!< IP Address, for EIDQUERY (string) */
207 #define DUNDI_IE_CACHEBYPASS            29      /*!< Bypass cache (empty) */
208
209 #define DUNDI_IE_PEERSTATUS             30      /*!< Peer/peer status (struct dundi_peer_status) */
210
211 #define DUNDI_FLUFF_TIME                2000    /*!< Amount of time for answer */
212 #define DUNDI_TTL_TIME                  200     /*!< Incremental average time */
213
214 #define DUNDI_DEFAULT_RETRANS           5
215 #define DUNDI_DEFAULT_RETRANS_TIMER     1000
216 #define DUNDI_DEFAULT_TTL               120     /*!< In seconds/hops like TTL */
217 #define DUNDI_DEFAULT_VERSION           1
218 #define DUNDI_DEFAULT_CACHE_TIME        3600    /*!< In seconds */
219 #define DUNDI_DEFAULT_KEY_EXPIRE        3600    /*!< Life of shared key In seconds */
220 #define DUNDI_DEF_EMPTY_CACHE_TIME      60      /*!< In seconds, cache of empty answer */
221 #define DUNDI_WINDOW                    1       /*!< Max 1 message in window */
222
223 #define DEFAULT_MAXMS                   2000
224
225 struct dundi_result {
226         unsigned int flags;
227         int weight;
228         int expiration;
229         int techint;
230         dundi_eid eid;
231         char eid_str[20];
232         char tech[10];
233         char dest[256];
234 };
235
236 struct dundi_entity_info {
237         char country[80];
238         char stateprov[80];
239         char locality[80];
240         char org[80];
241         char orgunit[80];
242         char email[80];
243         char phone[80]; 
244         char ipaddr[80];
245 };
246
247 /*! 
248  * \brief Lookup the given number in the given dundi context.
249  * Lookup number in a given dundi context (if unspecified use e164), the given callerid (if specified) 
250  * and return up to maxret results in the array specified.
251  * \retval the number of results found.
252  * \retval -1 on a hangup of the channel. 
253 */
254 int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache);
255
256 /*! \brief Retrieve information on a specific EID */
257 int dundi_query_eid(struct dundi_entity_info *dei, const char *dcontext, dundi_eid eid);
258
259 /*! \brief Pre-cache to push upstream peers */
260 int dundi_precache(const char *dcontext, const char *number);
261
262 #endif /* _ASTERISK_DUNDI_H */