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