1 /* 2 * SNMPStats Module 3 * Copyright (C) 2006 SOMA Networks, INC. 4 * Written by: Jeffrey Magder (jmagder@somanetworks.com) 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 it 9 * 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, but 14 * WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * 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 21 * USA 22 * 23 * This file defines the prototypes that implement the kamailioSIPRegUserTable. 24 * For a full description of the table, please see the KAMAILIO-SIP-SERVER-MIB. 25 * 26 * Understanding this code will be much simpler with the following information: 27 * 28 * 1) All rows are indexed by an integer user index. This is different from the 29 * usrloc module, which indexes by strings. This less natural indexing 30 * scheme was required due to SNMP String index limitations. (for example, 31 * SNMP has maximum index lengths.) 32 * 33 * 2) We need a quick way of mapping usrloc indices to our integer indices. For 34 * this reason a string indexed Hash Table was created, with each entry mapping 35 * to an integer user index. 36 * 37 * This hash table is used by the kamailioSIPContactTable (the hash table also 38 * maps a user to its contacts), as well as the kamailioSIPRegUserLookupTable. 39 * The hash table is also used for quick lookups when a user expires. (i.e, it 40 * gives us a more direct reference, instead of having to search the whole 41 * table). 42 * 43 * 3) We are informed about new/expired users via a callback mechanism from the 44 * usrloc module. Because of NetSNMP inefficiencies, we had to abstract this 45 * process. Specifically: 46 * 47 * - It can take a long time for the NetSNMP code base to populate a table with 48 * a large number of records. 49 * 50 * - We rely on callbacks for updated user information. 51 * 52 * Clearly, using the SNMPStats module in this situation could lead to some 53 * big performance loses if we don't find another way to deal with this. The 54 * solution was to use an interprocess communications buffer. 55 * 56 * Instead of adding the record directly to the table, the callback functions 57 * now adds either an add/delete command to the interprocessBuffer. When an 58 * snmp request is received by the SNMPStats sub-process, it will consume 59 * this interprocess buffer, adding and deleting users. When it is finished, 60 * it can service the SNMP request. 61 * 62 * This doesn't remove the NetSNMP inefficiency, but instead moves it to a 63 * non-critical path. Such an approach allows SNMP support with almost no 64 * overhead to the rest of Kamailio. 65 */ 66 67 #ifndef KAMAILIOSIPREGUSERTABLE_H 68 #define KAMAILIOSIPREGUSERTABLE_H 69 70 #ifdef __cplusplus 71 extern "C" { 72 #endif 73 74 #include <net-snmp/net-snmp-config.h> 75 #include <net-snmp/library/container.h> 76 #include <net-snmp/agent/table_array.h> 77 78 #include "../../core/config.h" 79 80 /* Defines what each SNMP Row is made of. */ 81 typedef struct kamailioSIPRegUserTable_context_s 82 { 83 netsnmp_index index; 84 85 unsigned long kamailioSIPUserIndex; 86 87 /* There are potentially a lot of these of varying sizes, so lets 88 * allocate only the amount of memory we need when the row is 89 * created. */ 90 unsigned char *kamailioSIPUserUri; 91 92 long kamailioSIPUserUri_len; 93 94 unsigned long kamailioSIPUserAuthenticationFailures; 95 96 void *data; 97 98 } kamailioSIPRegUserTable_context; 99 100 /*******************************/ 101 /* Customized Prototypes */ 102 /*******************************/ 103 104 /* If the usrloc module is loaded, this function will grab hooks into its 105 * callback registration function, and add handleContactCallbacks() as the 106 * callback for UL_CONTACT_INSERT and UL_CONTACT_EXPIRE. 107 * 108 * Returns 1 on success, and zero otherwise */ 109 int registerForUSRLOCCallbacks(void); 110 111 /* 112 * Creates a row and inserts it. 113 * 114 * Returns: The rows userIndex on success, and 0 otherwise. 115 */ 116 int createRegUserRow(char *stringToRegister); 117 118 119 /* Removes an SNMP row indexed by userIndex, and frees the string and index it 120 * pointed to. */ 121 void deleteRegUserRow(int userIndex); 122 123 /* Creates an 'aor to userindex' record from stringName and userIndex, and pushes 124 * them onto the hash table. */ 125 void pushUserIntoHashTable(int userIndex, char *stringName); 126 127 /* 128 * Adds or updates a user: 129 * 130 * - If a user with the name userName exists, its 'number of contacts' count 131 * will be incremented. 132 * - If the user doesn't exist, the user will be added to the table, and its 133 * number of contacts' count set to 1. 134 */ 135 void updateUser(char *userName); 136 137 /*******************************/ 138 /* Normal Function Prototypes */ 139 /*******************************/ 140 141 /* Initializes the kamailioSIPRegUserTable module. */ 142 void init_kamailioSIPRegUserTable(void); 143 144 /* 145 * Initialize the kamailioSIPRegUserTable table by defining its contents and how 146 * it's structured 147 */ 148 void initialize_table_kamailioSIPRegUserTable(void); 149 150 const kamailioSIPRegUserTable_context *kamailioSIPRegUserTable_get_by_idx( 151 netsnmp_index *); 152 153 const kamailioSIPRegUserTable_context *kamailioSIPRegUserTable_get_by_idx_rs( 154 netsnmp_index *, int row_status); 155 156 /* Handles SNMP GET requests. */ 157 int kamailioSIPRegUserTable_get_value( 158 netsnmp_request_info *, netsnmp_index *, netsnmp_table_request_info *); 159 160 /* OID Declarations. */ 161 extern oid kamailioSIPRegUserTable_oid[]; 162 extern size_t kamailioSIPRegUserTable_oid_len; 163 164 #define kamailioSIPRegUserTable_TABLE_OID KAMAILIO_OID, 3, 1, 2, 1, 5, 6 165 166 /* Column Definitions */ 167 #define COLUMN_KAMAILIOSIPUSERINDEX 1 168 #define COLUMN_KAMAILIOSIPUSERURI 2 169 #define COLUMN_KAMAILIOSIPUSERAUTHENTICATIONFAILURES 3 170 171 #define kamailioSIPRegUserTable_COL_MIN 2 172 #define kamailioSIPRegUserTable_COL_MAX 3 173 174 #ifdef __cplusplus 175 } 176 #endif 177 178 #endif /** KAMAILIOSIPREGUSERTABLE_H */