Core Update of doxygen, removal of history, changing "ser" to "kamailio"
[sip-router] / qvalue.h
1 /*
2  * Handling of the q value
3  *
4  * Copyright (C) 2004 FhG FOKUS
5  *
6  * This file is part of Kamailio, a free SIP server.
7  *
8  * Kamailio is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version
12  *
13  * Kamailio is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License 
19  * along with this program; if not, write to the Free Software 
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
21  *
22  */
23 /*!
24  * \file
25  * \brief Kamailio core :: Handling of the Q value
26  * \author janakj
27  * \ingroup core
28  * Module: \ref core
29  */
30
31 #ifndef _QVALUE_H
32 #define _QVALUE_H 1
33
34 #include <string.h>
35
36 /*
37  * The q value expresses the priority of a URI within a set of URIs 
38  * (Contact header field in the same SIP message or dset array in 
39  * ser. The higher is the q value of a URI the higher is the priority 
40  * of the URI.
41  *
42  * The q value is usually expressed as a floating point number with 
43  * limited number of decimal digits, for example 0.346. RFC3261 allows 
44  * 0-3 decimal digits.
45  *
46  * To speed things up we represent the q value as integer number, it 
47  * is then easier to handle/print the value. To convert float into 
48  * integer we multiply the q value by 1000, i.e. 
49  * (float)0.567 == (int)567. In the opposite direction, values 
50  * higher or equal to 1000 are converted to 1.0 and values below or 
51  * equal to 0 are converted to 0.
52  *
53  * Value Q_UNSPECIFIED (which is in fact -1) has a special meaning, it 
54  * means that the q value is not known and the parameter should not be 
55  * printed when printing Contacts, implementations will then use 
56  * implementation specific pre-defined values.
57  */
58
59 typedef int qvalue_t;
60
61 /*
62  * Use this if the value of q is not specified
63  */
64 #define Q_UNSPECIFIED ((qvalue_t)-1)
65
66
67 #define MAX_Q ((qvalue_t)1000)
68 #define MIN_Q ((qvalue_t)0)
69
70 #define MAX_Q_STR "1"
71 #define MAX_Q_STR_LEN (sizeof(MAX_Q_STR) - 1)
72
73 #define MIN_Q_STR "0"
74 #define MIN_Q_STR_LEN (sizeof(MIN_Q_STR) - 1)
75
76 #define Q_PREFIX "0."
77 #define Q_PREFIX_LEN (sizeof(Q_PREFIX) - 1)
78
79
80
81 /*
82  * Calculate the length of printed q
83  */
84 static inline size_t len_q(qvalue_t q)
85 {
86         if (q == Q_UNSPECIFIED) {
87                 return 0;
88         } else if (q >= MAX_Q) {
89                 return MAX_Q_STR_LEN;
90         } else if (q <= MIN_Q) {
91                 return MIN_Q_STR_LEN;
92         } else if (q % 100 == 0) {
93                 return Q_PREFIX_LEN + 1;
94         } else if (q % 10 == 0) {
95                 return Q_PREFIX_LEN + 2;
96         } else {
97                 return Q_PREFIX_LEN + 3;
98         }
99 }
100
101
102 /*
103  * Convert qvalue_t to double
104  */
105 static inline double q2double(qvalue_t q)
106 {
107         if (q == Q_UNSPECIFIED) {
108                 return -1;
109         } else {
110                 return (double)((double)q / (double)1000);
111         }
112 }
113
114
115 /*
116  * Convert double to qvalue_t
117  */
118 static inline qvalue_t double2q(double q)
119 {
120         if (q == -1) {
121                 return Q_UNSPECIFIED;
122         } else {
123                 return q * 1000;
124         }
125 }
126
127
128 /*
129  * Convert q value to string
130  */
131 static inline char* q2str(qvalue_t q, unsigned int* len)
132 {
133         static char buf[sizeof("0.123")];
134         char* p;
135
136         p = buf;
137         if (q == Q_UNSPECIFIED) {
138                      /* Do nothing */
139         } else if (q >= MAX_Q) {
140                 memcpy(p, MAX_Q_STR, MAX_Q_STR_LEN);
141                 p += MAX_Q_STR_LEN;
142         } else if (q <= MIN_Q) {
143                 memcpy(p, MIN_Q_STR, MIN_Q_STR_LEN);
144                 p += MIN_Q_STR_LEN;
145         } else {
146                 memcpy(p, Q_PREFIX, Q_PREFIX_LEN);
147                 p += Q_PREFIX_LEN;
148                 
149                 *p++ = q / 100 + '0';
150                 q %= 100;
151                 if (!q) goto end;
152
153                 *p++ = q / 10 + '0';
154                 q %= 10;
155                 if (!q) goto end;
156
157                 *p++ = q + '0';
158         }
159  end:
160         *p = '\0';
161         if (len) {
162                 *len = p - buf;
163         }
164         return buf;
165 }
166
167
168 /*
169  * Convert string representation of q parameter in qvalue_t
170  */
171 int str2q(qvalue_t* q, char* s, int len);
172
173
174 #endif /* _QVALUE_H */