1 /* 2 * Copyright (C) 2001-2003 FhG Fokus 3 * 4 * This file is part of Kamailio, a free SIP server. 5 * 6 * Kamailio is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version 10 * 11 * Kamailio is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 #ifndef str_h 22 #define str_h 23 24 #include <string.h> 25 26 /** @defgroup str_string Counted-Length Strings 27 * @{ 28 * 29 * Implementation of counted-length strings. In SER and its modules, strings 30 * are often stored in the ::str structure. In addition to the pointer 31 * pointing to the first character of the string, the structure also contains 32 * the length of the string. 33 * 34 * @section motivation Motivation 35 * Storing the length of the string together with the pointer to the string 36 * has two advantages. First, it makes many string operations faster because 37 * it is not necessary to count the number of characters at runtime. Second, 38 * the pointer can point to arbitrary substrings within a SIP message (which 39 * itself is stored as one long string spanning the whole message) without the 40 * need to make a zero-terminated copy of it. 41 * 42 * @section drawbacks Drawbacks 43 * Note well that the fact that a string stored 44 * using this data structure are not guaranteed to be zero terminated (by 45 * default they're not) makes them a little incovenient to use with many 46 * standard libc string functions, because these usually expect the input 47 * to be zero-terminated. 48 * In this case you have to either make a zero-terminated copy or inject the 49 * terminating zero behind the actuall string (if possible). Note that 50 * injecting a zero terminating characters is considered to be dangerous. 51 * The functions shm_str_dup() and pkg_str_dup() will always create a 52 * zero-terminated copy. 53 */ 54 55 /** @file 56 * This header field defines the ::str data structure that is used across 57 * SER sources to store counted-length strings. The file also defines several 58 * convenience macros. 59 */ 60 61 /** Data structure used across SER sources to store counted-length strings. 62 * This is the data structure that is used to store counted-length 63 * strings in SER core and modules. 64 */ 65 struct _str{ 66 char* s; /**< Pointer to the first character of the string */ 67 int len; /**< Length of the string */ 68 }; 69 70 71 /** Data structure used across SER sources to store counted-length strings. 72 * @see _str 73 */ 74 typedef struct _str str; 75 76 /** Initializes static ::str string with string literal. 77 * This is a convenience macro that can be used to initialize 78 * static ::str strings with string literals like this: 79 * \code static str var = STR_STATIC_INIT("some_string"); \endcode 80 * @param v is a string literal 81 * @sa STR_NULL 82 */ 83 #define STR_STATIC_INIT(v) {(v), sizeof(v) - 1} 84 85 /* kamailio compatibility macro (same thing as above) */ 86 #define str_init(v) STR_STATIC_INIT(v) 87 88 /** Initializes ::str string with NULL pointer and zero length. 89 * This is a convenience macro that can be used to initialize 90 * ::str string variable to NULL string with zero length: 91 * \code str var = STR_NULL; \endcode 92 * @sa STR_STATIC_INIT 93 */ 94 #define STR_NULL {0, 0} 95 96 /** Formats ::str string for use in printf-like functions. 97 * This is a macro that prepares a ::str string for use in functions which 98 * use printf-like formatting strings. This macro is necessary because 99 * ::str strings do not have to be zero-terminated and thus it is necessary 100 * to provide printf-like functions with the number of characters in the 101 * string manually. Here is an example how to use the macro: 102 * \code printf("%.*s\n", STR_FMT(var));\endcode Note well that the correct 103 * sequence in the formatting string is %.*, see the man page of printf for 104 * more details. 105 */ 106 #define STR_FMT(_pstr_) \ 107 ((_pstr_ != (str *)0) ? (_pstr_)->len : 0), \ 108 ((_pstr_ != (str *)0) ? (_pstr_)->s : "") 109 110 111 /** Compares two ::str strings. 112 * This macro implements comparison of two strings represented using ::str 113 * structures. First it compares the lengths of both string and if and only 114 * if they are same then both strings are compared using memcmp. 115 * @param x is first string to be compared 116 * @param y is second string to be compared 117 * @return 1 if strings are same, 0 otherwise 118 */ 119 #define STR_EQ(x,y) (((x).len == (y).len) && \ 120 (memcmp((x).s, (y).s, (x).len) == 0)) 121 122 /** 123 * If c != '\0', backup c in v and set c = '\0' 124 * - useful to terminate str->s with '\0' (if not already '\0'), keeping original 125 * value in v, to be able to restore with STR_ZTOV(...) 126 */ 127 #define STR_VTOZ(c,v) do { \ 128 v = '\0'; \ 129 if(c!='\0') { \ 130 v = c; \ 131 c = '\0'; \ 132 } \ 133 } while(0) 134 135 /** 136 * If v != '\0', set c = v 137 * - restore original value after using STR_VTOZ(...) 138 */ 139 #define STR_ZTOV(c,v) do { \ 140 if (v != '\0') { \ 141 c = v; \ 142 } \ 143 } while(0) 144 145 /** 146 * str with value: not null and not emptu 147 */ 148 #define STR_WITHVAL(_sp) ((_sp) && ((_sp)->s) && ((_sp)->len)) 149 150 /** @} */ 151 152 /** Appends a sufffix 153 * @param orig is the original string 154 * @param suffix is the suffix string 155 * @param dest is the result ::str of appending suffix to orig 156 * @return 0 if ok -1 if error 157 * remember to free the dest->s private memory 158 */ 159 int str_append(str *orig, str *suffix, str *dest); 160 161 char* _strnstr(const char *s, const char *find, size_t slen); 162 char* _strnistr(const char *s, const char *find, size_t slen); 163 164 #endif 165