Asterisk - The Open Source Telephony Project  21.4.1
dundi.h
Go to the documentation of this file.
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 */
56  /*! IAX, version 2 */
58  /*! SIP - Session Initiation Protocol, RFC 3261 */
60  /*! ITU H.323 */
62  /*! PJSIP */
64 };
65 
66 enum {
67  /*! Isn't and can't be a valid number */
69  /*! Is a valid number */
70  DUNDI_FLAG_EXISTS = (1 << 0),
71  /*! Might be valid if you add more digits */
73  /*! Might be a match */
74  DUNDI_FLAG_CANMATCH = (1 << 2),
75  /*! Keep dialtone */
77  /*! Destination known to be residential */
79  /*! Destination known to be commercial */
81  /*! Destination known to be cellular/mobile */
82  DUNDI_FLAG_MOBILE = (1 << 6),
83  /*! No unsolicited calls of any kind through this route */
85  /*! No commercial unsolicited calls through this route */
87 };
88 
89 enum {
90  DUNDI_HINT_NONE = (0),
91  /*! TTL Expired */
93  /*! Don't ask for anything beginning with data */
94  DUNDI_HINT_DONT_ASK = (1 << 1),
95  /*! Answer not affected by entity list */
97 };
98 
99 struct dundi_encblock { /*!< AES-128 encrypted block */
100  unsigned char iv[16]; /*!< Initialization vector of random data */
101  unsigned char encdata[0]; /*!< Encrypted / compressed data */
102 } __attribute__((__packed__));
103 
104 struct dundi_answer {
105  dundi_eid eid; /*!< Original source of answer */
106  unsigned char protocol; /*!< Protocol (DUNDI_PROTO_*) */
107  unsigned short flags; /*!< Flags relating to answer */
108  unsigned short weight; /*!< Weight of answers */
109  unsigned char data[0]; /*!< Protocol specific URI */
110 } __attribute__((__packed__));
111 
112 struct dundi_hint {
113  unsigned short flags; /*!< Flags relating to answer */
114  unsigned char data[0]; /*!< For data for hint */
115 } __attribute__((__packed__));
116 
117 enum {
118  /*! Success */
120  /*! General unspecified failure */
122  /*! Requested entity is dynamic */
124  /*! No or improper authorization */
126  /*! Duplicate request */
128  /*! Expired TTL */
130  /*! Need new session key to decode */
132  /*! Badly encrypted data */
134 };
135 
136 struct dundi_cause {
137  unsigned char causecode; /*!< Numerical cause (DUNDI_CAUSE_*) */
138  char desc[0]; /*!< Textual description */
139 } __attribute__((__packed__));
140 
142  unsigned int flags;
143  unsigned short netlag;
144  unsigned short querylag;
145  dundi_eid peereid;
146 } __attribute__((__packed__));
147 
148 enum {
149  DUNDI_PEER_PRIMARY = (1 << 0),
150  DUNDI_PEER_SECONDARY = (1 << 1),
151  DUNDI_PEER_UNAVAILABLE = (1 << 2),
152  DUNDI_PEER_REGISTERED = (1 << 3),
153  DUNDI_PEER_MOD_OUTBOUND = (1 << 4),
154  DUNDI_PEER_MOD_INBOUND = (1 << 5),
155  DUNDI_PEER_PCMOD_OUTBOUND = (1 << 6),
156  DUNDI_PEER_PCMOD_INBOUND = (1 << 7),
157 };
158 
159 #define DUNDI_COMMAND_FINAL (0x80) /*!< Or'd with other flags */
160 
161 #define DUNDI_COMMAND_ACK (0 | 0x40) /*!< Ack a message */
162 #define DUNDI_COMMAND_DPDISCOVER 1 /*!< Request discovery */
163 #define DUNDI_COMMAND_DPRESPONSE (2 | 0x40) /*!< Respond to a discovery request */
164 #define DUNDI_COMMAND_EIDQUERY 3 /*!< Request information for a peer */
165 #define DUNDI_COMMAND_EIDRESPONSE (4 | 0x40) /*!< Response to a peer query */
166 #define DUNDI_COMMAND_PRECACHERQ 5 /*!< Pre-cache Request */
167 #define DUNDI_COMMAND_PRECACHERP (6 | 0x40) /*!< Pre-cache Response */
168 #define DUNDI_COMMAND_INVALID (7 | 0x40) /*!< Invalid dialog state (does not require ack) */
169 #define DUNDI_COMMAND_UNKNOWN (8 | 0x40) /*!< Unknown command */
170 #define DUNDI_COMMAND_NULL 9 /*!< No-op */
171 #define DUNDI_COMMAND_REGREQ (10) /*!< Register Request */
172 #define DUNDI_COMMAND_REGRESPONSE (11 | 0x40) /*!< Register Response */
173 #define DUNDI_COMMAND_CANCEL (12) /*!< Cancel transaction entirely */
174 #define DUNDI_COMMAND_ENCRYPT (13) /*!< Send an encrypted message */
175 #define DUNDI_COMMAND_ENCREJ (14 | 0x40) /*!< Reject an encrypted message */
176 
177 #define DUNDI_COMMAND_STATUS 15 /*!< Status command */
178 
179 /*
180  * Remember that some information elements may occur
181  * more than one time within a message
182  */
183 
184 #define DUNDI_IE_EID 1 /*!< Entity identifier (dundi_eid) */
185 #define DUNDI_IE_CALLED_CONTEXT 2 /*!< DUNDi Context (string) */
186 #define DUNDI_IE_CALLED_NUMBER 3 /*!< Number of equivalent (string) */
187 #define DUNDI_IE_EID_DIRECT 4 /*!< Entity identifier (dundi_eid), direct connect */
188 #define DUNDI_IE_ANSWER 5 /*!< An answer (struct dundi_answer) */
189 #define DUNDI_IE_TTL 6 /*!< Max TTL for this request / Remaining TTL for the response (short)*/
190 #define DUNDI_IE_VERSION 10 /*!< DUNDi version (should be 1) (short) */
191 #define DUNDI_IE_EXPIRATION 11 /*!< Recommended expiration (short) */
192 #define DUNDI_IE_UNKNOWN 12 /*!< Unknown command (byte) */
193 #define DUNDI_IE_CAUSE 14 /*!< Success or cause of failure */
194 #define DUNDI_IE_REQEID 15 /*!< EID being requested for EIDQUERY*/
195 #define DUNDI_IE_ENCDATA 16 /*!< AES-128 encrypted data */
196 #define DUNDI_IE_SHAREDKEY 17 /*!< RSA encrypted AES-128 key */
197 #define DUNDI_IE_SIGNATURE 18 /*!< RSA Signature of encrypted shared key */
198 #define DUNDI_IE_KEYCRC32 19 /*!< CRC32 of encrypted key (int) */
199 #define DUNDI_IE_HINT 20 /*!< Answer hints */
200 
201 #define DUNDI_IE_DEPARTMENT 21 /*!< Department, for EIDQUERY (string) */
202 #define DUNDI_IE_ORGANIZATION 22 /*!< Organization, for EIDQUERY (string) */
203 #define DUNDI_IE_LOCALITY 23 /*!< City/Locality, for EIDQUERY (string) */
204 #define DUNDI_IE_STATE_PROV 24 /*!< State/Province, for EIDQUERY (string) */
205 #define DUNDI_IE_COUNTRY 25 /*!< Country, for EIDQUERY (string) */
206 #define DUNDI_IE_EMAIL 26 /*!< E-mail addy, for EIDQUERY (string) */
207 #define DUNDI_IE_PHONE 27 /*!< Contact Phone, for EIDQUERY (string) */
208 #define DUNDI_IE_IPADDR 28 /*!< IP Address, for EIDQUERY (string) */
209 #define DUNDI_IE_CACHEBYPASS 29 /*!< Bypass cache (empty) */
210 
211 #define DUNDI_IE_PEERSTATUS 30 /*!< Peer/peer status (struct dundi_peer_status) */
212 
213 #define DUNDI_FLUFF_TIME 2000 /*!< Amount of time for answer */
214 #define DUNDI_TTL_TIME 200 /*!< Incremental average time */
215 
216 #define DUNDI_DEFAULT_RETRANS 5
217 #define DUNDI_DEFAULT_RETRANS_TIMER 1000
218 #define DUNDI_DEFAULT_TTL 120 /*!< In seconds/hops like TTL */
219 #define DUNDI_DEFAULT_VERSION 1
220 #define DUNDI_DEFAULT_CACHE_TIME 3600 /*!< In seconds */
221 #define DUNDI_DEFAULT_KEY_EXPIRE 3600 /*!< Life of shared key In seconds */
222 #define DUNDI_DEF_EMPTY_CACHE_TIME 60 /*!< In seconds, cache of empty answer */
223 #define DUNDI_WINDOW 1 /*!< Max 1 message in window */
224 
225 #define DEFAULT_MAXMS 2000
226 
227 struct dundi_result {
228  unsigned int flags;
229  int weight;
230  int expiration;
231  int techint;
232  dundi_eid eid;
233  char eid_str[20];
234  char tech[10];
235  char dest[256];
236 };
237 
239  char country[80];
240  char stateprov[80];
241  char locality[80];
242  char org[80];
243  char orgunit[80];
244  char email[80];
245  char phone[80];
246  char ipaddr[80];
247 };
248 
249 /*!
250  * \brief Lookup the given number in the given dundi context.
251  * Lookup number in a given dundi context (if unspecified use e164), the given callerid (if specified)
252  * and return up to maxret results in the array specified.
253  * \retval the number of results found.
254  * \retval -1 on a hangup of the channel.
255 */
256 int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache);
257 
258 /*! \brief Retrieve information on a specific EID */
259 int dundi_query_eid(struct dundi_entity_info *dei, const char *dcontext, dundi_eid eid);
260 
261 /*! \brief Pre-cache to push upstream peers */
262 int dundi_precache(const char *dcontext, const char *number);
263 
264 #endif /* _ASTERISK_DUNDI_H */
Main Channel structure associated with a channel.
int dundi_precache(const char *dcontext, const char *number)
Pre-cache to push upstream peers.
Definition: pbx_dundi.c:4074
unsigned char encdata[0]
Definition: dundi.h:101
int dundi_query_eid(struct dundi_entity_info *dei, const char *dcontext, dundi_eid eid)
Retrieve information on a specific EID.
Definition: pbx_dundi.c:4127
unsigned char cmdresp
Definition: dundi.h:39
unsigned char oseqno
Definition: dundi.h:38
An Entity ID is essentially a MAC address, brief and unique.
Definition: utils.h:813
Utility functions.
Number structure.
Definition: app_followme.c:154
unsigned char data[0]
Definition: dundi.h:114
unsigned short flags
Definition: dundi.h:107
unsigned char protocol
Definition: dundi.h:106
General Asterisk PBX channel definitions.
unsigned char cmdflags
Definition: dundi.h:40
int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache)
Lookup the given number in the given dundi context. Lookup number in a given dundi context (if unspec...
Definition: pbx_dundi.c:3932
unsigned short flags
Definition: dundi.h:113
unsigned short weight
Definition: dundi.h:108
unsigned short strans
Definition: dundi.h:35
unsigned char iv[16]
Definition: dundi.h:100
char desc[0]
Definition: dundi.h:138
unsigned char causecode
Definition: dundi.h:137
dundi_eid eid
Definition: dundi.h:105
unsigned short dtrans
Definition: dundi.h:36
unsigned char data[0]
Definition: dundi.h:109
unsigned char iseqno
Definition: dundi.h:37