1 /* 2 * FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application 3 * Copyright (C) 2005-2014, Anthony Minessale II <anthm@freeswitch.org> 4 * 5 * Version: MPL 1.1 6 * 7 * The contents of this file are subject to the Mozilla Public License Version 8 * 1.1 (the "License"); you may not use this file except in compliance with 9 * the License. You may obtain a copy of the License at 10 * http://www.mozilla.org/MPL/ 11 * 12 * Software distributed under the License is distributed on an "AS IS" basis, 13 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 14 * for the specific language governing rights and limitations under the 15 * License. 16 * 17 * The Original Code is FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application 18 * 19 * The Initial Developer of the Original Code is 20 * Anthony Minessale II <anthm@freeswitch.org> 21 * Portions created by the Initial Developer are Copyright (C) 22 * the Initial Developer. All Rights Reserved. 23 * 24 * Contributor(s): 25 * 26 * Anthony Minessale II <anthm@freeswitch.org> 27 * Eliot Gable <egable@gmail.com> 28 * 29 * switch_apr.h -- APR includes header 30 * 31 */ 32 /*! \file switch_apr.h 33 \brief APR includes header 34 35 The things powered by APR are renamed into the switch_ namespace to provide a cleaner 36 look to things and helps me to document what parts of APR I am using I'd like to take this 37 opportunity to thank APR for all the awesome stuff it does and for making my life much easier. 38 39 */ 40 #ifndef SWITCH_APR_H 41 #define SWITCH_APR_H 42 43 SWITCH_BEGIN_EXTERN_C 44 45 SWITCH_DECLARE(int) switch_status_is_timeup(int status); 46 47 #ifdef WIN32 48 typedef DWORD switch_thread_id_t; 49 #else 50 #include <pthread.h> 51 typedef pthread_t switch_thread_id_t; 52 #endif 53 54 SWITCH_DECLARE(switch_thread_id_t) switch_thread_self(void); 55 56 /*! \brief Compare two thread ids 57 * \param tid1 1st Thread ID to compare 58 * \param tid2 2nd Thread ID to compare 59 */ 60 SWITCH_DECLARE(int) switch_thread_equal(switch_thread_id_t tid1, switch_thread_id_t tid2); 61 62 63 /* 64 The pieces of apr we allow ppl to pass around between modules we typedef into our namespace and wrap all the functions 65 any other apr code should be as hidden as possible. 66 */ 67 /** 68 * @defgroup switch_apr Brought To You By APR 69 * @ingroup FREESWITCH 70 * @{ 71 */ 72 /** 73 * @defgroup switch_memory_pool Memory Pool Functions 74 * @ingroup switch_apr 75 * @{ 76 */ 77 /** The fundamental pool type */ 78 /* see switch types.h typedef struct apr_pool_t switch_memory_pool_t;*/ 79 /** 80 * Clear all memory in the pool and run all the cleanups. This also destroys all 81 * subpools. 82 * @param pool The pool to clear 83 * @remark This does not actually free the memory, it just allows the pool 84 * to re-use this memory for the next allocation. 85 * @see apr_pool_destroy() 86 */ 87 SWITCH_DECLARE(void) switch_pool_clear(switch_memory_pool_t *pool); 88 89 /** @} */ 90 91 /** 92 * @defgroup switch_string String Handling funcions 93 * @ingroup switch_apr 94 * @{ 95 */ 96 97 SWITCH_DECLARE(int) switch_snprintf(_Out_z_cap_(len) 98 char *buf, _In_ switch_size_t len, _In_z_ _Printf_format_string_ const char *format, ...); 99 100 SWITCH_DECLARE(int) switch_vasprintf(_Out_opt_ char **buf, _In_z_ _Printf_format_string_ const char *format, _In_ va_list ap); 101 102 SWITCH_DECLARE(int) switch_vsnprintf(char *buf, switch_size_t len, const char *format, va_list ap); 103 104 SWITCH_DECLARE(char *) switch_copy_string(_Out_z_cap_(dst_size) 105 char *dst, _In_z_ const char *src, _In_ switch_size_t dst_size); 106 107 /** @} */ 108 109 #if 0 110 /** 111 * @defgroup apr_hash Hash Tables 112 * @ingroup switch_apr 113 * @{ 114 */ 115 116 /** Abstract type for hash tables. */ 117 typedef struct apr_hash_t switch_hash_t; 118 119 /** Abstract type for scanning hash tables. */ 120 typedef struct apr_hash_index_t switch_hash_index_t; 121 122 /** 123 * When passing a key to switch_hashfunc_default, this value can be 124 * passed to indicate a string-valued key, and have the length compute automatically. 125 * 126 */ 127 #define SWITCH_HASH_KEY_STRING (-1) 128 129 /** 130 * Start iterating over the entries in a hash table. 131 * @param p The pool to allocate the switch_hash_index_t iterator. If this 132 * pool is NULL, then an internal, non-thread-safe iterator is used. 133 * @param ht The hash table 134 * @remark There is no restriction on adding or deleting hash entries during 135 * an iteration (although the results may be unpredictable unless all you do 136 * is delete the current entry) and multiple iterations can be in 137 * progress at the same time. 138 139 */ 140 SWITCH_DECLARE(switch_hash_index_t *) switch_core_hash_first(switch_memory_pool_t *pool, switch_hash_t *ht); 141 142 /** 143 * Continue iterating over the entries in a hash table. 144 * @param ht The iteration state 145 * @return a pointer to the updated iteration state. NULL if there are no more 146 * entries. 147 */ 148 SWITCH_DECLARE(switch_hash_index_t *) switch_core_hash_next(switch_hash_index_t *ht); 149 150 /** 151 * Get the current entry's details from the iteration state. 152 * @param hi The iteration state 153 * @param key Return pointer for the pointer to the key. 154 * @param klen Return pointer for the key length. 155 * @param val Return pointer for the associated value. 156 * @remark The return pointers should point to a variable that will be set to the 157 * corresponding data, or they may be NULL if the data isn't interesting. 158 */ 159 SWITCH_DECLARE(void) switch_core_hash_this(switch_hash_index_t *hi, const void **key, switch_ssize_t *klen, void **val); 160 161 162 163 SWITCH_DECLARE(switch_memory_pool_t *) switch_hash_pool_get(switch_hash_t *ht); 164 165 /** @} */ 166 167 168 #endif 169 170 /** 171 * The default hash function. 172 * @param key pointer to the key. 173 * @param klen the key length. 174 * 175 */ 176 SWITCH_DECLARE(unsigned int) switch_hashfunc_default(const char *key, switch_ssize_t *klen); 177 178 SWITCH_DECLARE(unsigned int) switch_ci_hashfunc_default(const char *char_key, switch_ssize_t *klen); 179 180 181 /** 182 * @defgroup switch_time Time Routines 183 * @ingroup switch_apr 184 * @{ 185 */ 186 187 /** number of microseconds since 00:00:00 january 1, 1970 UTC */ 188 typedef int64_t switch_time_t; 189 190 /** number of microseconds in the interval */ 191 typedef int64_t switch_interval_time_t; 192 193 /** 194 * a structure similar to ANSI struct tm with the following differences: 195 * - tm_usec isn't an ANSI field 196 * - tm_gmtoff isn't an ANSI field (it's a bsdism) 197 */ 198 typedef struct switch_time_exp_t { 199 /** microseconds past tm_sec */ 200 int32_t tm_usec; 201 /** (0-61) seconds past tm_min */ 202 int32_t tm_sec; 203 /** (0-59) minutes past tm_hour */ 204 int32_t tm_min; 205 /** (0-23) hours past midnight */ 206 int32_t tm_hour; 207 /** (1-31) day of the month */ 208 int32_t tm_mday; 209 /** (0-11) month of the year */ 210 int32_t tm_mon; 211 /** year since 1900 */ 212 int32_t tm_year; 213 /** (0-6) days since sunday */ 214 int32_t tm_wday; 215 /** (0-365) days since jan 1 */ 216 int32_t tm_yday; 217 /** daylight saving time */ 218 int32_t tm_isdst; 219 /** seconds east of UTC */ 220 int32_t tm_gmtoff; 221 } switch_time_exp_t; 222 223 SWITCH_DECLARE(switch_time_t) switch_time_make(switch_time_t sec, int32_t usec); 224 225 /** 226 * @return the current time 227 */ 228 SWITCH_DECLARE(switch_time_t) switch_time_now(void); 229 230 /** 231 * Convert time value from human readable format to a numeric apr_time_t that 232 * always represents GMT 233 * @param result the resulting imploded time 234 * @param input the input exploded time 235 */ 236 SWITCH_DECLARE(switch_status_t) switch_time_exp_gmt_get(switch_time_t *result, switch_time_exp_t *input); 237 238 /** 239 * formats the exploded time according to the format specified 240 * @param s string to write to 241 * @param retsize The length of the returned string 242 * @param max The maximum length of the string 243 * @param format The format for the time string 244 * @param tm The time to convert 245 */ 246 SWITCH_DECLARE(switch_status_t) switch_strftime(char *s, switch_size_t *retsize, switch_size_t max, const char *format, switch_time_exp_t *tm); 247 248 /** 249 * formats the exploded time according to the format specified (does not validate format string) 250 * @param s string to write to 251 * @param retsize The length of the returned string 252 * @param max The maximum length of the string 253 * @param format The format for the time string 254 * @param tm The time to convert 255 */ 256 SWITCH_DECLARE(switch_status_t) switch_strftime_nocheck(char *s, switch_size_t *retsize, switch_size_t max, const char *format, switch_time_exp_t *tm); 257 258 /** 259 * switch_rfc822_date formats dates in the RFC822 260 * format in an efficient manner. It is a fixed length 261 * format which requires the indicated amount of storage, 262 * including the trailing NUL terminator. 263 * @param date_str String to write to. 264 * @param t the time to convert 265 */ 266 SWITCH_DECLARE(switch_status_t) switch_rfc822_date(char *date_str, switch_time_t t); 267 268 /** 269 * convert a time to its human readable components in GMT timezone 270 * @param result the exploded time 271 * @param input the time to explode 272 */ 273 SWITCH_DECLARE(switch_status_t) switch_time_exp_gmt(switch_time_exp_t *result, switch_time_t input); 274 275 /** 276 * Convert time value from human readable format to a numeric apr_time_t 277 * e.g. elapsed usec since epoch 278 * @param result the resulting imploded time 279 * @param input the input exploded time 280 */ 281 SWITCH_DECLARE(switch_status_t) switch_time_exp_get(switch_time_t *result, switch_time_exp_t *input); 282 283 /** 284 * convert a time to its human readable components in local timezone 285 * @param result the exploded time 286 * @param input the time to explode 287 */ 288 SWITCH_DECLARE(switch_status_t) switch_time_exp_lt(switch_time_exp_t *result, switch_time_t input); 289 290 /** 291 * convert a time to its human readable components in a specific timezone with offset 292 * @param result the exploded time 293 * @param input the time to explode 294 */ 295 SWITCH_DECLARE(switch_status_t) switch_time_exp_tz(switch_time_exp_t *result, switch_time_t input, switch_int32_t offs); 296 297 /** 298 * Sleep for the specified number of micro-seconds. 299 * @param t desired amount of time to sleep. 300 * @warning May sleep for longer than the specified time. 301 */ 302 SWITCH_DECLARE(void) switch_sleep(switch_interval_time_t t); 303 SWITCH_DECLARE(void) switch_micro_sleep(switch_interval_time_t t); 304 305 /** @} */ 306 307 /** 308 * @defgroup switch_thread_mutex Thread Mutex Routines 309 * @ingroup switch_apr 310 * @{ 311 */ 312 313 /** Opaque thread-local mutex structure */ 314 typedef struct apr_thread_mutex_t switch_mutex_t; 315 316 /** Lock Flags */ 317 #define SWITCH_MUTEX_DEFAULT 0x0 /**< platform-optimal lock behavior */ 318 #define SWITCH_MUTEX_NESTED 0x1 /**< enable nested (recursive) locks */ 319 #define SWITCH_MUTEX_UNNESTED 0x2 /**< disable nested locks */ 320 321 /** 322 * Create and initialize a mutex that can be used to synchronize threads. 323 * @param lock the memory address where the newly created mutex will be 324 * stored. 325 * @param flags Or'ed value of: 326 * <PRE> 327 * SWITCH_THREAD_MUTEX_DEFAULT platform-optimal lock behavior. 328 * SWITCH_THREAD_MUTEX_NESTED enable nested (recursive) locks. 329 * SWITCH_THREAD_MUTEX_UNNESTED disable nested locks (non-recursive). 330 * </PRE> 331 * @param pool the pool from which to allocate the mutex. 332 * @warning Be cautious in using SWITCH_THREAD_MUTEX_DEFAULT. While this is the 333 * most optimial mutex based on a given platform's performance charateristics, 334 * it will behave as either a nested or an unnested lock. 335 * 336 */ 337 SWITCH_DECLARE(switch_status_t) switch_mutex_init(switch_mutex_t ** lock, unsigned int flags, switch_memory_pool_t *pool); 338 339 340 /** 341 * Destroy the mutex and free the memory associated with the lock. 342 * @param lock the mutex to destroy. 343 */ 344 SWITCH_DECLARE(switch_status_t) switch_mutex_destroy(switch_mutex_t *lock); 345 346 /** 347 * Acquire the lock for the given mutex. If the mutex is already locked, 348 * the current thread will be put to sleep until the lock becomes available. 349 * @param lock the mutex on which to acquire the lock. 350 */ 351 SWITCH_DECLARE(switch_status_t) switch_mutex_lock(switch_mutex_t *lock); 352 353 /** 354 * Release the lock for the given mutex. 355 * @param lock the mutex from which to release the lock. 356 */ 357 SWITCH_DECLARE(switch_status_t) switch_mutex_unlock(switch_mutex_t *lock); 358 359 /** 360 * Attempt to acquire the lock for the given mutex. If the mutex has already 361 * been acquired, the call returns immediately with APR_EBUSY. Note: it 362 * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine 363 * if the return value was APR_EBUSY, for portability reasons. 364 * @param lock the mutex on which to attempt the lock acquiring. 365 */ 366 SWITCH_DECLARE(switch_status_t) switch_mutex_trylock(switch_mutex_t *lock); 367 368 /** @} */ 369 370 /** 371 * @defgroup switch_atomic Multi-Threaded Adtomic Operations Routines 372 * @ingroup switch_apr 373 * @{ 374 */ 375 376 /** Opaque type used for the atomic operations */ 377 #ifdef apr_atomic_t 378 typedef apr_atomic_t switch_atomic_t; 379 #else 380 typedef uint32_t switch_atomic_t; 381 #endif 382 383 /** 384 * Some architectures require atomic operations internal structures to be 385 * initialized before use. 386 * @param pool The memory pool to use when initializing the structures. 387 */ 388 SWITCH_DECLARE(switch_status_t) switch_atomic_init(switch_memory_pool_t *pool); 389 390 /** 391 * Uses an atomic operation to read the uint32 value at the location specified 392 * by mem. 393 * @param mem The location of memory which stores the value to read. 394 */ 395 SWITCH_DECLARE(uint32_t) switch_atomic_read(volatile switch_atomic_t *mem); 396 397 /** 398 * Uses an atomic operation to set a uint32 value at a specified location of 399 * memory. 400 * @param mem The location of memory to set. 401 * @param val The uint32 value to set at the memory location. 402 */ 403 SWITCH_DECLARE(void) switch_atomic_set(volatile switch_atomic_t *mem, uint32_t val); 404 405 /** 406 * Uses an atomic operation to add the uint32 value to the value at the 407 * specified location of memory. 408 * @param mem The location of the value to add to. 409 * @param val The uint32 value to add to the value at the memory location. 410 */ 411 SWITCH_DECLARE(void) switch_atomic_add(volatile switch_atomic_t *mem, uint32_t val); 412 413 /** 414 * Uses an atomic operation to increment the value at the specified memroy 415 * location. 416 * @param mem The location of the value to increment. 417 */ 418 SWITCH_DECLARE(void) switch_atomic_inc(volatile switch_atomic_t *mem); 419 420 /** 421 * Uses an atomic operation to decrement the value at the specified memroy 422 * location. 423 * @param mem The location of the value to decrement. 424 */ 425 SWITCH_DECLARE(int) switch_atomic_dec(volatile switch_atomic_t *mem); 426 427 /** @} */ 428 429 /** 430 * @defgroup switch_thread_rwlock Thread Read/Write lock Routines 431 * @ingroup switch_apr 432 * @{ 433 */ 434 435 /** Opaque structure used for the rwlock */ 436 typedef struct apr_thread_rwlock_t switch_thread_rwlock_t; 437 438 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_create(switch_thread_rwlock_t ** rwlock, switch_memory_pool_t *pool); 439 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_destroy(switch_thread_rwlock_t *rwlock); 440 SWITCH_DECLARE(switch_memory_pool_t *) switch_thread_rwlock_pool_get(switch_thread_rwlock_t *rwlock); 441 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_rdlock(switch_thread_rwlock_t *rwlock); 442 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_tryrdlock(switch_thread_rwlock_t *rwlock); 443 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_wrlock(switch_thread_rwlock_t *rwlock); 444 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_trywrlock(switch_thread_rwlock_t *rwlock); 445 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_trywrlock_timeout(switch_thread_rwlock_t *rwlock, int timeout); 446 SWITCH_DECLARE(switch_status_t) switch_thread_rwlock_unlock(switch_thread_rwlock_t *rwlock); 447 448 /** @} */ 449 450 /** 451 * @defgroup switch_thread_cond Condition Variable Routines 452 * @ingroup switch_apr 453 * @{ 454 */ 455 456 /** 457 * Note: destroying a condition variable (or likewise, destroying or 458 * clearing the pool from which a condition variable was allocated) if 459 * any threads are blocked waiting on it gives undefined results. 460 */ 461 462 /** Opaque structure for thread condition variables */ 463 typedef struct apr_thread_cond_t switch_thread_cond_t; 464 465 /** 466 * Create and initialize a condition variable that can be used to signal 467 * and schedule threads in a single process. 468 * @param cond the memory address where the newly created condition variable 469 * will be stored. 470 * @param pool the pool from which to allocate the mutex. 471 */ 472 SWITCH_DECLARE(switch_status_t) switch_thread_cond_create(switch_thread_cond_t ** cond, switch_memory_pool_t *pool); 473 474 /** 475 * Put the active calling thread to sleep until signaled to wake up. Each 476 * condition variable must be associated with a mutex, and that mutex must 477 * be locked before calling this function, or the behavior will be 478 * undefined. As the calling thread is put to sleep, the given mutex 479 * will be simultaneously released; and as this thread wakes up the lock 480 * is again simultaneously acquired. 481 * @param cond the condition variable on which to block. 482 * @param mutex the mutex that must be locked upon entering this function, 483 * is released while the thread is asleep, and is again acquired before 484 * returning from this function. 485 */ 486 SWITCH_DECLARE(switch_status_t) switch_thread_cond_wait(switch_thread_cond_t *cond, switch_mutex_t *mutex); 487 488 /** 489 * Put the active calling thread to sleep until signaled to wake up or 490 * the timeout is reached. Each condition variable must be associated 491 * with a mutex, and that mutex must be locked before calling this 492 * function, or the behavior will be undefined. As the calling thread 493 * is put to sleep, the given mutex will be simultaneously released; 494 * and as this thread wakes up the lock is again simultaneously acquired. 495 * @param cond the condition variable on which to block. 496 * @param mutex the mutex that must be locked upon entering this function, 497 * is released while the thread is asleep, and is again acquired before 498 * returning from this function. 499 * @param timeout The amount of time in microseconds to wait. This is 500 * a maximum, not a minimum. If the condition is signaled, we 501 * will wake up before this time, otherwise the error APR_TIMEUP 502 * is returned. 503 */ 504 SWITCH_DECLARE(switch_status_t) switch_thread_cond_timedwait(switch_thread_cond_t *cond, switch_mutex_t *mutex, switch_interval_time_t timeout); 505 506 /** 507 * Signals a single thread, if one exists, that is blocking on the given 508 * condition variable. That thread is then scheduled to wake up and acquire 509 * the associated mutex. Although it is not required, if predictable scheduling 510 * is desired, that mutex must be locked while calling this function. 511 * @param cond the condition variable on which to produce the signal. 512 */ 513 SWITCH_DECLARE(switch_status_t) switch_thread_cond_signal(switch_thread_cond_t *cond); 514 515 /** 516 * Signals all threads blocking on the given condition variable. 517 * Each thread that was signaled is then scheduled to wake up and acquire 518 * the associated mutex. This will happen in a serialized manner. 519 * @param cond the condition variable on which to produce the broadcast. 520 */ 521 SWITCH_DECLARE(switch_status_t) switch_thread_cond_broadcast(switch_thread_cond_t *cond); 522 523 /** 524 * Destroy the condition variable and free the associated memory. 525 * @param cond the condition variable to destroy. 526 */ 527 SWITCH_DECLARE(switch_status_t) switch_thread_cond_destroy(switch_thread_cond_t *cond); 528 529 /** @} */ 530 531 /** 532 * @defgroup switch_UUID UUID Handling 533 * @ingroup switch_apr 534 * @{ 535 */ 536 537 /** we represent a UUID as a block of 16 bytes. */ 538 539 typedef struct { 540 unsigned char data[16]; 541 /**< the actual UUID */ 542 } switch_uuid_t; 543 544 /** UUIDs are formatted as: 00112233-4455-6677-8899-AABBCCDDEEFF */ 545 #define SWITCH_UUID_FORMATTED_LENGTH 256 546 547 #define SWITCH_MD5_DIGESTSIZE 16 548 #define SWITCH_MD5_DIGEST_STRING_SIZE 33 549 550 /** 551 * Format a UUID into a string, following the standard format 552 * @param buffer The buffer to place the formatted UUID string into. It must 553 * be at least APR_UUID_FORMATTED_LENGTH + 1 bytes long to hold 554 * the formatted UUID and a null terminator 555 * @param uuid The UUID to format 556 */ 557 SWITCH_DECLARE(void) switch_uuid_format(char *buffer, const switch_uuid_t *uuid); 558 559 /** 560 * Generate and return a (new) UUID 561 * @param uuid The resulting UUID 562 */ 563 SWITCH_DECLARE(void) switch_uuid_get(switch_uuid_t *uuid); 564 565 /** 566 * Parse a standard-format string into a UUID 567 * @param uuid The resulting UUID 568 * @param uuid_str The formatted UUID 569 */ 570 SWITCH_DECLARE(switch_status_t) switch_uuid_parse(switch_uuid_t *uuid, const char *uuid_str); 571 572 /** 573 * MD5 in one step 574 * @param digest The final MD5 digest 575 * @param input The message block to use 576 * @param inputLen The length of the message block 577 */ 578 SWITCH_DECLARE(switch_status_t) switch_md5(unsigned char digest[SWITCH_MD5_DIGESTSIZE], const void *input, switch_size_t inputLen); 579 SWITCH_DECLARE(switch_status_t) switch_md5_string(char digest_str[SWITCH_MD5_DIGEST_STRING_SIZE], const void *input, switch_size_t inputLen); 580 581 /** @} */ 582 583 /** 584 * @defgroup switch_FIFO Thread Safe FIFO bounded queue 585 * @ingroup switch_apr 586 * @{ 587 */ 588 589 /** Opaque structure used for queue API */ 590 typedef struct apr_queue_t switch_queue_t; 591 592 /** 593 * create a FIFO queue 594 * @param queue The new queue 595 * @param queue_capacity maximum size of the queue 596 * @param pool a pool to allocate queue from 597 */ 598 SWITCH_DECLARE(switch_status_t) switch_queue_create(switch_queue_t ** queue, unsigned int queue_capacity, switch_memory_pool_t *pool); 599 600 /** 601 * pop/get an object from the queue, blocking if the queue is already empty 602 * 603 * @param queue the queue 604 * @param data the data 605 * @returns APR_EINTR the blocking was interrupted (try again) 606 * @returns APR_EOF if the queue has been terminated 607 * @returns APR_SUCCESS on a successfull pop 608 */ 609 SWITCH_DECLARE(switch_status_t) switch_queue_pop(switch_queue_t *queue, void **data); 610 611 /** 612 * pop/get an object from the queue, blocking if the queue is already empty 613 * 614 * @param queue the queue 615 * @param data the data 616 * @param timeout The amount of time in microseconds to wait. This is 617 * a maximum, not a minimum. If the condition is signaled, we 618 * will wake up before this time, otherwise the error APR_TIMEUP 619 * is returned. 620 * @returns APR_TIMEUP the request timed out 621 * @returns APR_EINTR the blocking was interrupted (try again) 622 * @returns APR_EOF if the queue has been terminated 623 * @returns APR_SUCCESS on a successfull pop 624 */ 625 SWITCH_DECLARE(switch_status_t) switch_queue_pop_timeout(switch_queue_t *queue, void **data, switch_interval_time_t timeout); 626 627 /** 628 * push/add a object to the queue, blocking if the queue is already full 629 * 630 * @param queue the queue 631 * @param data the data 632 * @returns APR_EINTR the blocking was interrupted (try again) 633 * @returns APR_EOF the queue has been terminated 634 * @returns APR_SUCCESS on a successfull push 635 */ 636 SWITCH_DECLARE(switch_status_t) switch_queue_push(switch_queue_t *queue, void *data); 637 638 /** 639 * returns the size of the queue. 640 * 641 * @warning this is not threadsafe, and is intended for reporting/monitoring 642 * of the queue. 643 * @param queue the queue 644 * @returns the size of the queue 645 */ 646 SWITCH_DECLARE(unsigned int) switch_queue_size(switch_queue_t *queue); 647 648 /** 649 * pop/get an object to the queue, returning immediatly if the queue is empty 650 * 651 * @param queue the queue 652 * @param data the data 653 * @returns APR_EINTR the blocking operation was interrupted (try again) 654 * @returns APR_EAGAIN the queue is empty 655 * @returns APR_EOF the queue has been terminated 656 * @returns APR_SUCCESS on a successfull push 657 */ 658 SWITCH_DECLARE(switch_status_t) switch_queue_trypop(switch_queue_t *queue, void **data); 659 660 SWITCH_DECLARE(switch_status_t) switch_queue_interrupt_all(switch_queue_t *queue); 661 662 SWITCH_DECLARE(switch_status_t) switch_queue_term(switch_queue_t *queue); 663 664 /** 665 * push/add a object to the queue, returning immediatly if the queue is full 666 * 667 * @param queue the queue 668 * @param data the data 669 * @returns APR_EINTR the blocking operation was interrupted (try again) 670 * @returns APR_EAGAIN the queue is full 671 * @returns APR_EOF the queue has been terminated 672 * @returns APR_SUCCESS on a successfull push 673 */ 674 SWITCH_DECLARE(switch_status_t) switch_queue_trypush(switch_queue_t *queue, void *data); 675 676 /** @} */ 677 678 /** 679 * @defgroup switch_file_io File I/O Handling Functions 680 * @ingroup switch_apr 681 * @{ 682 */ 683 684 /** Structure for referencing files. */ 685 typedef struct apr_file_t switch_file_t; 686 687 typedef int32_t switch_fileperms_t; 688 typedef int switch_seek_where_t; 689 690 /** 691 * @defgroup apr_file_seek_flags File Seek Flags 692 * @{ 693 */ 694 695 /* flags for apr_file_seek */ 696 /** Set the file position */ 697 #define SWITCH_SEEK_SET SEEK_SET 698 /** Current */ 699 #define SWITCH_SEEK_CUR SEEK_CUR 700 /** Go to end of file */ 701 #define SWITCH_SEEK_END SEEK_END 702 /** @} */ 703 704 705 /** 706 * @defgroup switch_file_permissions File Permissions flags 707 * @ingroup switch_file_io 708 * @{ 709 */ 710 711 #define SWITCH_FPROT_USETID 0x8000 /**< Set user id */ 712 #define SWITCH_FPROT_UREAD 0x0400 /**< Read by user */ 713 #define SWITCH_FPROT_UWRITE 0x0200 /**< Write by user */ 714 #define SWITCH_FPROT_UEXECUTE 0x0100 /**< Execute by user */ 715 716 #define SWITCH_FPROT_GSETID 0x4000 /**< Set group id */ 717 #define SWITCH_FPROT_GREAD 0x0040 /**< Read by group */ 718 #define SWITCH_FPROT_GWRITE 0x0020 /**< Write by group */ 719 #define SWITCH_FPROT_GEXECUTE 0x0010 /**< Execute by group */ 720 721 #define SWITCH_FPROT_WSTICKY 0x2000 722 #define SWITCH_FPROT_WREAD 0x0004 /**< Read by others */ 723 #define SWITCH_FPROT_WWRITE 0x0002 /**< Write by others */ 724 #define SWITCH_FPROT_WEXECUTE 0x0001 /**< Execute by others */ 725 726 #define SWITCH_FPROT_OS_DEFAULT 0x0FFF /**< use OS's default permissions */ 727 728 /* additional permission flags for apr_file_copy and apr_file_append */ 729 #define SWITCH_FPROT_FILE_SOURCE_PERMS 0x1000 /**< Copy source file's permissions */ 730 /** @} */ 731 732 /* File lock types/flags */ 733 /** 734 * @defgroup switch_file_lock_types File Lock Types 735 * @{ 736 */ 737 738 #define SWITCH_FLOCK_SHARED 1 /**< Shared lock. More than one process 739 or thread can hold a shared lock 740 at any given time. Essentially, 741 this is a "read lock", preventing 742 writers from establishing an 743 exclusive lock. */ 744 #define SWITCH_FLOCK_EXCLUSIVE 2 /**< Exclusive lock. Only one process 745 may hold an exclusive lock at any 746 given time. This is analogous to 747 a "write lock". */ 748 749 #define SWITCH_FLOCK_TYPEMASK 0x000F /**< mask to extract lock type */ 750 #define SWITCH_FLOCK_NONBLOCK 0x0010 /**< do not block while acquiring the 751 file lock */ 752 753 /** @} */ 754 755 /** 756 * @defgroup switch_file_open_flags File Open Flags/Routines 757 * @ingroup switch_file_io 758 * @{ 759 */ 760 #define SWITCH_FOPEN_READ 0x00001 /**< Open the file for reading */ 761 #define SWITCH_FOPEN_WRITE 0x00002 /**< Open the file for writing */ 762 #define SWITCH_FOPEN_CREATE 0x00004 /**< Create the file if not there */ 763 #define SWITCH_FOPEN_APPEND 0x00008 /**< Append to the end of the file */ 764 #define SWITCH_FOPEN_TRUNCATE 0x00010 /**< Open the file and truncate to 0 length */ 765 #define SWITCH_FOPEN_BINARY 0x00020 /**< Open the file in binary mode */ 766 #define SWITCH_FOPEN_EXCL 0x00040 /**< Open should fail if APR_CREATE and file exists. */ 767 #define SWITCH_FOPEN_BUFFERED 0x00080 /**< Open the file for buffered I/O */ 768 #define SWITCH_FOPEN_DELONCLOSE 0x00100 /**< Delete the file after close */ 769 #define SWITCH_FOPEN_XTHREAD 0x00200 /**< Platform dependent tag to open the file for use across multiple threads */ 770 #define SWITCH_FOPEN_SHARELOCK 0x00400 /**< Platform dependent support for higher level locked read/write access to support writes across process/machines */ 771 #define SWITCH_FOPEN_NOCLEANUP 0x00800 /**< Do not register a cleanup when the file is opened */ 772 #define SWITCH_FOPEN_SENDFILE_ENABLED 0x01000 /**< Advisory flag that this file should support apr_socket_sendfile operation */ 773 #define SWITCH_FOPEN_LARGEFILE 0x04000 /**< Platform dependent flag to enable large file support */ 774 /** @} */ 775 776 /** 777 * Open the specified file. 778 * @param newf The opened file descriptor. 779 * @param fname The full path to the file (using / on all systems) 780 * @param flag Or'ed value of: 781 * <PRE> 782 * SWITCH_FOPEN_READ open for reading 783 * SWITCH_FOPEN_WRITE open for writing 784 * SWITCH_FOPEN_CREATE create the file if not there 785 * SWITCH_FOPEN_APPEND file ptr is set to end prior to all writes 786 * SWITCH_FOPEN_TRUNCATE set length to zero if file exists 787 * SWITCH_FOPEN_BINARY not a text file (This flag is ignored on 788 * UNIX because it has no meaning) 789 * SWITCH_FOPEN_BUFFERED buffer the data. Default is non-buffered 790 * SWITCH_FOPEN_EXCL return error if APR_CREATE and file exists 791 * SWITCH_FOPEN_DELONCLOSE delete the file after closing. 792 * SWITCH_FOPEN_XTHREAD Platform dependent tag to open the file 793 * for use across multiple threads 794 * SWITCH_FOPEN_SHARELOCK Platform dependent support for higher 795 * level locked read/write access to support 796 * writes across process/machines 797 * SWITCH_FOPEN_NOCLEANUP Do not register a cleanup with the pool 798 * passed in on the <EM>pool</EM> argument (see below). 799 * The apr_os_file_t handle in apr_file_t will not 800 * be closed when the pool is destroyed. 801 * SWITCH_FOPEN_SENDFILE_ENABLED Open with appropriate platform semantics 802 * for sendfile operations. Advisory only, 803 * apr_socket_sendfile does not check this flag. 804 * </PRE> 805 * @param perm Access permissions for file. 806 * @param pool The pool to use. 807 * @remark If perm is SWITCH_FPROT_OS_DEFAULT and the file is being created, 808 * appropriate default permissions will be used. 809 */ 810 SWITCH_DECLARE(switch_status_t) switch_file_open(switch_file_t ** newf, const char *fname, int32_t flag, switch_fileperms_t perm, 811 switch_memory_pool_t *pool); 812 813 814 SWITCH_DECLARE(switch_status_t) switch_file_seek(switch_file_t *thefile, switch_seek_where_t where, int64_t *offset); 815 816 817 SWITCH_DECLARE(switch_status_t) switch_file_copy(const char *from_path, const char *to_path, switch_fileperms_t perms, switch_memory_pool_t *pool); 818 819 /** 820 * Close the specified file. 821 * @param thefile The file descriptor to close. 822 */ 823 SWITCH_DECLARE(switch_status_t) switch_file_close(switch_file_t *thefile); 824 825 SWITCH_DECLARE(switch_status_t) switch_file_trunc(switch_file_t *thefile, int64_t offset); 826 827 SWITCH_DECLARE(switch_status_t) switch_file_lock(switch_file_t *thefile, int type); 828 829 /** 830 * Delete the specified file. 831 * @param path The full path to the file (using / on all systems) 832 * @param pool The pool to use. 833 * @remark If the file is open, it won't be removed until all 834 * instances are closed. 835 */ 836 SWITCH_DECLARE(switch_status_t) switch_file_remove(const char *path, switch_memory_pool_t *pool); 837 838 SWITCH_DECLARE(switch_status_t) switch_file_rename(const char *from_path, const char *to_path, switch_memory_pool_t *pool); 839 840 /** 841 * Read data from the specified file. 842 * @param thefile The file descriptor to read from. 843 * @param buf The buffer to store the data to. 844 * @param nbytes On entry, the number of bytes to read; on exit, the number 845 * of bytes read. 846 * 847 * @remark apr_file_read will read up to the specified number of 848 * bytes, but never more. If there isn't enough data to fill that 849 * number of bytes, all of the available data is read. The third 850 * argument is modified to reflect the number of bytes read. If a 851 * char was put back into the stream via ungetc, it will be the first 852 * character returned. 853 * 854 * @remark It is not possible for both bytes to be read and an APR_EOF 855 * or other error to be returned. APR_EINTR is never returned. 856 */ 857 SWITCH_DECLARE(switch_status_t) switch_file_read(switch_file_t *thefile, void *buf, switch_size_t *nbytes); 858 859 /** 860 * Write data to the specified file. 861 * @param thefile The file descriptor to write to. 862 * @param buf The buffer which contains the data. 863 * @param nbytes On entry, the number of bytes to write; on exit, the number 864 * of bytes written. 865 * 866 * @remark apr_file_write will write up to the specified number of 867 * bytes, but never more. If the OS cannot write that many bytes, it 868 * will write as many as it can. The third argument is modified to 869 * reflect the * number of bytes written. 870 * 871 * @remark It is possible for both bytes to be written and an error to 872 * be returned. APR_EINTR is never returned. 873 */ 874 SWITCH_DECLARE(switch_status_t) switch_file_write(switch_file_t *thefile, const void *buf, switch_size_t *nbytes); 875 SWITCH_DECLARE(int) switch_file_printf(switch_file_t *thefile, const char *format, ...); 876 877 SWITCH_DECLARE(switch_status_t) switch_file_mktemp(switch_file_t ** thefile, char *templ, int32_t flags, switch_memory_pool_t *pool); 878 879 SWITCH_DECLARE(switch_size_t) switch_file_get_size(switch_file_t *thefile); 880 881 SWITCH_DECLARE(switch_status_t) switch_file_exists(const char *filename, switch_memory_pool_t *pool); 882 883 SWITCH_DECLARE(switch_status_t) switch_directory_exists(const char *dirname, switch_memory_pool_t *pool); 884 885 /** 886 * Create a new directory on the file system. 887 * @param path the path for the directory to be created. (use / on all systems) 888 * @param perm Permissions for the new direcoty. 889 * @param pool the pool to use. 890 */ 891 SWITCH_DECLARE(switch_status_t) switch_dir_make(const char *path, switch_fileperms_t perm, switch_memory_pool_t *pool); 892 893 /** Creates a new directory on the file system, but behaves like 894 * 'mkdir -p'. Creates intermediate directories as required. No error 895 * will be reported if PATH already exists. 896 * @param path the path for the directory to be created. (use / on all systems) 897 * @param perm Permissions for the new direcoty. 898 * @param pool the pool to use. 899 */ 900 SWITCH_DECLARE(switch_status_t) switch_dir_make_recursive(const char *path, switch_fileperms_t perm, switch_memory_pool_t *pool); 901 902 typedef struct switch_dir switch_dir_t; 903 904 struct switch_array_header_t { 905 /** The pool the array is allocated out of */ 906 switch_memory_pool_t *pool; 907 /** The amount of memory allocated for each element of the array */ 908 int elt_size; 909 /** The number of active elements in the array */ 910 int nelts; 911 /** The number of elements allocated in the array */ 912 int nalloc; 913 /** The elements in the array */ 914 char *elts; 915 }; 916 typedef struct switch_array_header_t switch_array_header_t; 917 918 SWITCH_DECLARE(switch_status_t) switch_dir_open(switch_dir_t ** new_dir, const char *dirname, switch_memory_pool_t *pool); 919 SWITCH_DECLARE(switch_status_t) switch_dir_close(switch_dir_t *thedir); 920 SWITCH_DECLARE(const char *) switch_dir_next_file(switch_dir_t *thedir, char *buf, switch_size_t len); 921 SWITCH_DECLARE(uint32_t) switch_dir_count(switch_dir_t *thedir); 922 923 /** @} */ 924 925 /** 926 * @defgroup switch_thread_proc Threads and Process Functions 927 * @ingroup switch_apr 928 * @{ 929 */ 930 931 /** Opaque Thread structure. */ 932 typedef struct apr_thread_t switch_thread_t; 933 934 /** Opaque Thread attributes structure. */ 935 typedef struct apr_threadattr_t switch_threadattr_t; 936 937 /** 938 * The prototype for any APR thread worker functions. 939 * typedef void *(SWITCH_THREAD_FUNC *switch_thread_start_t)(switch_thread_t*, void*); 940 */ 941 typedef void *(SWITCH_THREAD_FUNC * switch_thread_start_t) (switch_thread_t *, void *); 942 943 //APR_DECLARE(apr_status_t) apr_threadattr_stacksize_set(apr_threadattr_t *attr, switch_size_t stacksize) 944 SWITCH_DECLARE(switch_status_t) switch_threadattr_stacksize_set(switch_threadattr_t *attr, switch_size_t stacksize); 945 946 SWITCH_DECLARE(switch_status_t) switch_threadattr_priority_set(switch_threadattr_t *attr, switch_thread_priority_t priority); 947 948 949 /** 950 * Create and initialize a new threadattr variable 951 * @param new_attr The newly created threadattr. 952 * @param pool The pool to use 953 */ 954 SWITCH_DECLARE(switch_status_t) switch_threadattr_create(switch_threadattr_t ** new_attr, switch_memory_pool_t *pool); 955 956 /** 957 * Set if newly created threads should be created in detached state. 958 * @param attr The threadattr to affect 959 * @param on Non-zero if detached threads should be created. 960 */ 961 SWITCH_DECLARE(switch_status_t) switch_threadattr_detach_set(switch_threadattr_t *attr, int32_t on); 962 963 /** 964 * Create a new thread of execution 965 * @param new_thread The newly created thread handle. 966 * @param attr The threadattr to use to determine how to create the thread 967 * @param func The function to start the new thread in 968 * @param data Any data to be passed to the starting function 969 * @param cont The pool to use 970 */ 971 SWITCH_DECLARE(switch_status_t) switch_thread_create(switch_thread_t ** new_thread, switch_threadattr_t *attr, 972 switch_thread_start_t func, void *data, switch_memory_pool_t *cont); 973 974 /** @} */ 975 976 /** 977 * @defgroup switch_network_io Network Routines 978 * @ingroup switch_apr 979 * @{ 980 */ 981 982 #define SWITCH_SO_LINGER 1 983 #define SWITCH_SO_KEEPALIVE 2 984 #define SWITCH_SO_DEBUG 4 985 #define SWITCH_SO_NONBLOCK 8 986 #define SWITCH_SO_REUSEADDR 16 987 #define SWITCH_SO_SNDBUF 64 988 #define SWITCH_SO_RCVBUF 128 989 #define SWITCH_SO_DISCONNECTED 256 990 #define SWITCH_SO_TCP_NODELAY 512 991 #define SWITCH_SO_TCP_KEEPIDLE 520 992 #define SWITCH_SO_TCP_KEEPINTVL 530 993 994 995 /** 996 * @def SWITCH_INET 997 * Not all platforms have these defined, so we'll define them here 998 * The default values come from FreeBSD 4.1.1 999 */ 1000 #define SWITCH_INET AF_INET 1001 #ifdef AF_INET6 1002 #define SWITCH_INET6 AF_INET6 1003 #else 1004 #define SWITCH_INET6 0 1005 #endif 1006 1007 /** @def SWITCH_UNSPEC 1008 * Let the system decide which address family to use 1009 */ 1010 #ifdef AF_UNSPEC 1011 #define SWITCH_UNSPEC AF_UNSPEC 1012 #else 1013 #define SWITCH_UNSPEC 0 1014 #endif 1015 1016 /** A structure to represent sockets */ 1017 typedef struct apr_socket_t switch_socket_t; 1018 1019 /** Freeswitch's socket address type, used to ensure protocol independence */ 1020 typedef struct apr_sockaddr_t switch_sockaddr_t; 1021 1022 typedef enum { 1023 SWITCH_SHUTDOWN_READ, /**< no longer allow read request */ 1024 SWITCH_SHUTDOWN_WRITE, /**< no longer allow write requests */ 1025 SWITCH_SHUTDOWN_READWRITE /**< no longer allow read or write requests */ 1026 } switch_shutdown_how_e; 1027 1028 /** 1029 * @defgroup IP_Proto IP Protocol Definitions for use when creating sockets 1030 * @{ 1031 */ 1032 #define SWITCH_PROTO_TCP 6 /**< TCP */ 1033 #define SWITCH_PROTO_UDP 17 /**< UDP */ 1034 #define SWITCH_PROTO_SCTP 132 /**< SCTP */ 1035 /** @} */ 1036 1037 /* function definitions */ 1038 1039 /** 1040 * Create a socket. 1041 * @param new_sock The new socket that has been set up. 1042 * @param family The address family of the socket (e.g., SWITCH_INET). 1043 * @param type The type of the socket (e.g., SOCK_STREAM). 1044 * @param protocol The protocol of the socket (e.g., SWITCH_PROTO_TCP). 1045 * @param pool The pool to use 1046 */ 1047 SWITCH_DECLARE(switch_status_t) switch_socket_create(switch_socket_t ** new_sock, int family, int type, int protocol, switch_memory_pool_t *pool); 1048 1049 /** 1050 * Shutdown either reading, writing, or both sides of a socket. 1051 * @param sock The socket to close 1052 * @param how How to shutdown the socket. One of: 1053 * <PRE> 1054 * SWITCH_SHUTDOWN_READ no longer allow read requests 1055 * SWITCH_SHUTDOWN_WRITE no longer allow write requests 1056 * SWITCH_SHUTDOWN_READWRITE no longer allow read or write requests 1057 * </PRE> 1058 * @see switch_shutdown_how_e 1059 * @remark This does not actually close the socket descriptor, it just 1060 * controls which calls are still valid on the socket. 1061 */ 1062 SWITCH_DECLARE(switch_status_t) switch_socket_shutdown(switch_socket_t *sock, switch_shutdown_how_e how); 1063 1064 /** 1065 * Close a socket. 1066 * @param sock The socket to close 1067 */ 1068 SWITCH_DECLARE(switch_status_t) switch_socket_close(switch_socket_t *sock); 1069 1070 /** 1071 * Bind the socket to its associated port 1072 * @param sock The socket to bind 1073 * @param sa The socket address to bind to 1074 * @remark This may be where we will find out if there is any other process 1075 * using the selected port. 1076 */ 1077 SWITCH_DECLARE(switch_status_t) switch_socket_bind(switch_socket_t *sock, switch_sockaddr_t *sa); 1078 1079 /** 1080 * Listen to a bound socket for connections. 1081 * @param sock The socket to listen on 1082 * @param backlog The number of outstanding connections allowed in the sockets 1083 * listen queue. If this value is less than zero, the listen 1084 * queue size is set to zero. 1085 */ 1086 SWITCH_DECLARE(switch_status_t) switch_socket_listen(switch_socket_t *sock, int32_t backlog); 1087 1088 /** 1089 * Accept a new connection request 1090 * @param new_sock A copy of the socket that is connected to the socket that 1091 * made the connection request. This is the socket which should 1092 * be used for all future communication. 1093 * @param sock The socket we are listening on. 1094 * @param pool The pool for the new socket. 1095 */ 1096 SWITCH_DECLARE(switch_status_t) switch_socket_accept(switch_socket_t ** new_sock, switch_socket_t *sock, switch_memory_pool_t *pool); 1097 1098 /** 1099 * Issue a connection request to a socket either on the same machine 1100 * or a different one. 1101 * @param sock The socket we wish to use for our side of the connection 1102 * @param sa The address of the machine we wish to connect to. 1103 */ 1104 SWITCH_DECLARE(switch_status_t) switch_socket_connect(switch_socket_t *sock, switch_sockaddr_t *sa); 1105 1106 /** 1107 * Get socket fd for the switch socket passed 1108 * @param sock The socket we wish to have fd 1109 */ 1110 SWITCH_DECLARE(int) switch_socket_fd_get(switch_socket_t *sock); 1111 1112 SWITCH_DECLARE(uint16_t) switch_sockaddr_get_port(switch_sockaddr_t *sa); 1113 SWITCH_DECLARE(const char *) switch_get_addr(char *buf, switch_size_t len, switch_sockaddr_t *in); 1114 SWITCH_DECLARE(switch_status_t) switch_getnameinfo(char **hostname, switch_sockaddr_t *sa, int32_t flags); 1115 SWITCH_DECLARE(int32_t) switch_sockaddr_get_family(switch_sockaddr_t *sa); 1116 SWITCH_DECLARE(switch_status_t) switch_sockaddr_ip_get(char **addr, switch_sockaddr_t *sa); 1117 SWITCH_DECLARE(int) switch_sockaddr_equal(const switch_sockaddr_t *sa1, const switch_sockaddr_t *sa2); 1118 1119 1120 /** 1121 * Create apr_sockaddr_t from hostname, address family, and port. 1122 * @param sa The new apr_sockaddr_t. 1123 * @param hostname The hostname or numeric address string to resolve/parse, or 1124 * NULL to build an address that corresponds to 0.0.0.0 or :: 1125 * @param family The address family to use, or SWITCH_UNSPEC if the system should 1126 * decide. 1127 * @param port The port number. 1128 * @param flags Special processing flags: 1129 * <PRE> 1130 * APR_IPV4_ADDR_OK first query for IPv4 addresses; only look 1131 * for IPv6 addresses if the first query failed; 1132 * only valid if family is APR_UNSPEC and hostname 1133 * isn't NULL; mutually exclusive with 1134 * APR_IPV6_ADDR_OK 1135 * APR_IPV6_ADDR_OK first query for IPv6 addresses; only look 1136 * for IPv4 addresses if the first query failed; 1137 * only valid if family is APR_UNSPEC and hostname 1138 * isn't NULL and APR_HAVE_IPV6; mutually exclusive 1139 * with APR_IPV4_ADDR_OK 1140 * </PRE> 1141 * @param pool The pool for the apr_sockaddr_t and associated storage. 1142 */ 1143 SWITCH_DECLARE(switch_status_t) switch_sockaddr_info_get(switch_sockaddr_t ** sa, const char *hostname, 1144 int32_t family, switch_port_t port, int32_t flags, switch_memory_pool_t *pool); 1145 1146 SWITCH_DECLARE(switch_status_t) switch_sockaddr_create(switch_sockaddr_t **sa, switch_memory_pool_t *pool); 1147 1148 /** 1149 * Send data over a network. 1150 * @param sock The socket to send the data over. 1151 * @param buf The buffer which contains the data to be sent. 1152 * @param len On entry, the number of bytes to send; on exit, the number 1153 * of bytes sent. 1154 * @remark 1155 * <PRE> 1156 * This functions acts like a blocking write by default. To change 1157 * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK 1158 * socket option. 1159 * 1160 * It is possible for both bytes to be sent and an error to be returned. 1161 * 1162 * APR_EINTR is never returned. 1163 * </PRE> 1164 */ 1165 SWITCH_DECLARE(switch_status_t) switch_socket_send(switch_socket_t *sock, const char *buf, switch_size_t *len); 1166 1167 /** 1168 * @param sock The socket to send from 1169 * @param where The apr_sockaddr_t describing where to send the data 1170 * @param flags The flags to use 1171 * @param buf The data to send 1172 * @param len The length of the data to send 1173 */ 1174 SWITCH_DECLARE(switch_status_t) switch_socket_sendto(switch_socket_t *sock, switch_sockaddr_t *where, int32_t flags, const char *buf, 1175 switch_size_t *len); 1176 1177 SWITCH_DECLARE(switch_status_t) switch_socket_send_nonblock(switch_socket_t *sock, const char *buf, switch_size_t *len); 1178 1179 /** 1180 * @param from The apr_sockaddr_t to fill in the recipient info 1181 * @param sock The socket to use 1182 * @param flags The flags to use 1183 * @param buf The buffer to use 1184 * @param len The length of the available buffer 1185 * 1186 */ 1187 SWITCH_DECLARE(switch_status_t) switch_socket_recvfrom(switch_sockaddr_t *from, switch_socket_t *sock, int32_t flags, char *buf, size_t *len); 1188 1189 SWITCH_DECLARE(switch_status_t) switch_socket_atmark(switch_socket_t *sock, int *atmark); 1190 1191 /** 1192 * Read data from a network. 1193 * @param sock The socket to read the data from. 1194 * @param buf The buffer to store the data in. 1195 * @param len On entry, the number of bytes to receive; on exit, the number 1196 * of bytes received. 1197 * @remark 1198 * <PRE> 1199 * This functions acts like a blocking read by default. To change 1200 * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK 1201 * socket option. 1202 * The number of bytes actually received is stored in argument 3. 1203 * 1204 * It is possible for both bytes to be received and an APR_EOF or 1205 * other error to be returned. 1206 * 1207 * APR_EINTR is never returned. 1208 * </PRE> 1209 */ 1210 SWITCH_DECLARE(switch_status_t) switch_socket_recv(switch_socket_t *sock, char *buf, switch_size_t *len); 1211 1212 /** 1213 * Setup socket options for the specified socket 1214 * @param sock The socket to set up. 1215 * @param opt The option we would like to configure. One of: 1216 * <PRE> 1217 * APR_SO_DEBUG -- turn on debugging information 1218 * APR_SO_KEEPALIVE -- keep connections active 1219 * APR_SO_LINGER -- lingers on close if data is present 1220 * APR_SO_NONBLOCK -- Turns blocking on/off for socket 1221 * When this option is enabled, use 1222 * the APR_STATUS_IS_EAGAIN() macro to 1223 * see if a send or receive function 1224 * could not transfer data without 1225 * blocking. 1226 * APR_SO_REUSEADDR -- The rules used in validating addresses 1227 * supplied to bind should allow reuse 1228 * of local addresses. 1229 * APR_SO_SNDBUF -- Set the SendBufferSize 1230 * APR_SO_RCVBUF -- Set the ReceiveBufferSize 1231 * </PRE> 1232 * @param on Value for the option. 1233 */ 1234 SWITCH_DECLARE(switch_status_t) switch_socket_opt_set(switch_socket_t *sock, int32_t opt, int32_t on); 1235 1236 /** 1237 * Query socket timeout for the specified socket 1238 * @param sock The socket to query 1239 * @param t Socket timeout returned from the query. 1240 * <PRE> 1241 * t > 0 -- read and write calls return APR_TIMEUP if specified time 1242 * elapsess with no data read or written 1243 * t == 0 -- read and write calls never block 1244 * t < 0 -- read and write calls block 1245 * </PRE> 1246 */ 1247 SWITCH_DECLARE(switch_status_t) switch_socket_timeout_get(switch_socket_t *sock, switch_interval_time_t *t); 1248 1249 /** 1250 * Setup socket timeout for the specified socket 1251 * @param sock The socket to set up. 1252 * @param t Value for the timeout. 1253 * <PRE> 1254 * t > 0 -- read and write calls return APR_TIMEUP if specified time 1255 * elapsess with no data read or written 1256 * t == 0 -- read and write calls never block 1257 * t < 0 -- read and write calls block 1258 * </PRE> 1259 */ 1260 SWITCH_DECLARE(switch_status_t) switch_socket_timeout_set(switch_socket_t *sock, switch_interval_time_t t); 1261 1262 /** 1263 * Join a Multicast Group 1264 * @param sock The socket to join a multicast group 1265 * @param join The address of the multicast group to join 1266 * @param iface Address of the interface to use. If NULL is passed, the 1267 * default multicast interface will be used. (OS Dependent) 1268 * @param source Source Address to accept transmissions from (non-NULL 1269 * implies Source-Specific Multicast) 1270 */ 1271 SWITCH_DECLARE(switch_status_t) switch_mcast_join(switch_socket_t *sock, switch_sockaddr_t *join, switch_sockaddr_t *iface, switch_sockaddr_t *source); 1272 1273 /** 1274 * Set the Multicast Time to Live (ttl) for a multicast transmission. 1275 * @param sock The socket to set the multicast ttl 1276 * @param ttl Time to live to Assign. 0-255, default=1 1277 * @remark If the TTL is 0, packets will only be seen by sockets on the local machine, 1278 * and only when multicast loopback is enabled. 1279 */ 1280 SWITCH_DECLARE(switch_status_t) switch_mcast_hops(switch_socket_t *sock, uint8_t ttl); 1281 1282 SWITCH_DECLARE(switch_status_t) switch_mcast_loopback(switch_socket_t *sock, uint8_t opt); 1283 SWITCH_DECLARE(switch_status_t) switch_mcast_interface(switch_socket_t *sock, switch_sockaddr_t *iface); 1284 1285 /** @} */ 1286 1287 typedef enum { 1288 SWITCH_NO_DESC, /**< nothing here */ 1289 SWITCH_POLL_SOCKET, /**< descriptor refers to a socket */ 1290 SWITCH_POLL_FILE, /**< descriptor refers to a file */ 1291 SWITCH_POLL_LASTDESC /**< descriptor is the last one in the list */ 1292 } switch_pollset_type_t; 1293 1294 typedef union { 1295 switch_file_t *f; /**< file */ 1296 switch_socket_t *s; /**< socket */ 1297 } switch_descriptor_t; 1298 1299 struct switch_pollfd { 1300 switch_memory_pool_t *p; /**< associated pool */ 1301 switch_pollset_type_t desc_type; 1302 /**< descriptor type */ 1303 int16_t reqevents; /**< requested events */ 1304 int16_t rtnevents; /**< returned events */ 1305 switch_descriptor_t desc; /**< @see apr_descriptor */ 1306 void *client_data; /**< allows app to associate context */ 1307 }; 1308 1309 1310 1311 /** 1312 * @defgroup apr_poll Poll Routines 1313 * @ingroup switch_apr 1314 * @{ 1315 */ 1316 /** Poll descriptor set. */ 1317 typedef struct switch_pollfd switch_pollfd_t; 1318 1319 /** Opaque structure used for pollset API */ 1320 typedef struct apr_pollset_t switch_pollset_t; 1321 1322 /** 1323 * Poll options 1324 */ 1325 #define SWITCH_POLLIN 0x001 /**< Can read without blocking */ 1326 #define SWITCH_POLLPRI 0x002 /**< Priority data available */ 1327 #define SWITCH_POLLOUT 0x004 /**< Can write without blocking */ 1328 #define SWITCH_POLLERR 0x010 /**< Pending error */ 1329 #define SWITCH_POLLHUP 0x020 /**< Hangup occurred */ 1330 #define SWITCH_POLLNVAL 0x040 /**< Descriptior invalid */ 1331 1332 /** 1333 * Setup a pollset object 1334 * @param pollset The pointer in which to return the newly created object 1335 * @param size The maximum number of descriptors that this pollset can hold 1336 * @param pool The pool from which to allocate the pollset 1337 * @param flags Optional flags to modify the operation of the pollset. 1338 * 1339 * @remark If flags equals APR_POLLSET_THREADSAFE, then a pollset is 1340 * created on which it is safe to make concurrent calls to 1341 * apr_pollset_add(), apr_pollset_remove() and apr_pollset_poll() from 1342 * separate threads. This feature is only supported on some 1343 * platforms; the apr_pollset_create() call will fail with 1344 * APR_ENOTIMPL on platforms where it is not supported. 1345 */ 1346 SWITCH_DECLARE(switch_status_t) switch_pollset_create(switch_pollset_t ** pollset, uint32_t size, switch_memory_pool_t *pool, uint32_t flags); 1347 1348 /** 1349 * Add a socket or file descriptor to a pollset 1350 * @param pollset The pollset to which to add the descriptor 1351 * @param descriptor The descriptor to add 1352 * @remark If you set client_data in the descriptor, that value 1353 * will be returned in the client_data field whenever this 1354 * descriptor is signalled in apr_pollset_poll(). 1355 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 1356 * and thread T1 is blocked in a call to apr_pollset_poll() for 1357 * this same pollset that is being modified via apr_pollset_add() 1358 * in thread T2, the currently executing apr_pollset_poll() call in 1359 * T1 will either: (1) automatically include the newly added descriptor 1360 * in the set of descriptors it is watching or (2) return immediately 1361 * with APR_EINTR. Option (1) is recommended, but option (2) is 1362 * allowed for implementations where option (1) is impossible 1363 * or impractical. 1364 */ 1365 SWITCH_DECLARE(switch_status_t) switch_pollset_add(switch_pollset_t *pollset, const switch_pollfd_t *descriptor); 1366 1367 /** 1368 * Remove a descriptor from a pollset 1369 * @param pollset The pollset from which to remove the descriptor 1370 * @param descriptor The descriptor to remove 1371 * @remark If the pollset has been created with APR_POLLSET_THREADSAFE 1372 * and thread T1 is blocked in a call to apr_pollset_poll() for 1373 * this same pollset that is being modified via apr_pollset_remove() 1374 * in thread T2, the currently executing apr_pollset_poll() call in 1375 * T1 will either: (1) automatically exclude the newly added descriptor 1376 * in the set of descriptors it is watching or (2) return immediately 1377 * with APR_EINTR. Option (1) is recommended, but option (2) is 1378 * allowed for implementations where option (1) is impossible 1379 * or impractical. 1380 */ 1381 SWITCH_DECLARE(switch_status_t) switch_pollset_remove(switch_pollset_t *pollset, const switch_pollfd_t *descriptor); 1382 1383 /** 1384 * Poll the sockets in the poll structure 1385 * @param aprset The poll structure we will be using. 1386 * @param numsock The number of sockets we are polling 1387 * @param nsds The number of sockets signalled. 1388 * @param timeout The amount of time in microseconds to wait. This is 1389 * a maximum, not a minimum. If a socket is signalled, we 1390 * will wake up before this time. A negative number means 1391 * wait until a socket is signalled. 1392 * @remark The number of sockets signalled is returned in the third argument. 1393 * This is a blocking call, and it will not return until either a 1394 * socket has been signalled, or the timeout has expired. 1395 */ 1396 SWITCH_DECLARE(switch_status_t) switch_poll(switch_pollfd_t *aprset, int32_t numsock, int32_t *nsds, switch_interval_time_t timeout); 1397 1398 /** 1399 * Block for activity on the descriptor(s) in a pollset 1400 * @param pollset The pollset to use 1401 * @param timeout Timeout in microseconds 1402 * @param num Number of signalled descriptors (output parameter) 1403 * @param descriptors Array of signalled descriptors (output parameter) 1404 */ 1405 SWITCH_DECLARE(switch_status_t) switch_pollset_poll(switch_pollset_t *pollset, switch_interval_time_t timeout, int32_t *num, const switch_pollfd_t **descriptors); 1406 1407 /*! 1408 \brief Create a set of file descriptors to poll from a socket 1409 \param poll the polfd to create 1410 \param sock the socket to add 1411 \param flags the flags to modify the behaviour 1412 \param pool the memory pool to use 1413 \return SWITCH_STATUS_SUCCESS when successful 1414 */ 1415 SWITCH_DECLARE(switch_status_t) switch_socket_create_pollset(switch_pollfd_t ** poll, switch_socket_t *sock, int16_t flags, switch_memory_pool_t *pool); 1416 1417 SWITCH_DECLARE(switch_interval_time_t) switch_interval_time_from_timeval(struct timeval *tvp); 1418 1419 1420 /*! 1421 \brief Create a pollfd out of a socket 1422 \param pollfd the pollfd to create 1423 \param sock the socket to add 1424 \param flags the flags to modify the behaviour 1425 \param client_data custom user data 1426 \param pool the memory pool to use 1427 \return SWITCH_STATUS_SUCCESS when successful 1428 */ 1429 SWITCH_DECLARE(switch_status_t) switch_socket_create_pollfd(switch_pollfd_t **pollfd, switch_socket_t *sock, int16_t flags, void *client_data, switch_memory_pool_t *pool); 1430 SWITCH_DECLARE(switch_status_t) switch_match_glob(const char *pattern, switch_array_header_t ** result, switch_memory_pool_t *pool); 1431 SWITCH_DECLARE(switch_status_t) switch_os_sock_get(switch_os_socket_t *thesock, switch_socket_t *sock); 1432 SWITCH_DECLARE(switch_status_t) switch_os_sock_put(switch_socket_t **sock, switch_os_socket_t *thesock, switch_memory_pool_t *pool); 1433 SWITCH_DECLARE(switch_status_t) switch_socket_addr_get(switch_sockaddr_t ** sa, switch_bool_t remote, switch_socket_t *sock); 1434 /** 1435 * Create an anonymous pipe. 1436 * @param in The file descriptor to use as input to the pipe. 1437 * @param out The file descriptor to use as output from the pipe. 1438 * @param pool The pool to operate on. 1439 */ 1440 SWITCH_DECLARE(switch_status_t) switch_file_pipe_create(switch_file_t ** in, switch_file_t ** out, switch_memory_pool_t *pool); 1441 1442 /** 1443 * Get the timeout value for a pipe or manipulate the blocking state. 1444 * @param thepipe The pipe we are getting a timeout for. 1445 * @param timeout The current timeout value in microseconds. 1446 */ 1447 SWITCH_DECLARE(switch_status_t) switch_file_pipe_timeout_get(switch_file_t *thepipe, switch_interval_time_t *timeout); 1448 1449 /** 1450 * Set the timeout value for a pipe or manipulate the blocking state. 1451 * @param thepipe The pipe we are setting a timeout on. 1452 * @param timeout The timeout value in microseconds. Values < 0 mean wait 1453 * forever, 0 means do not wait at all. 1454 */ 1455 SWITCH_DECLARE(switch_status_t) switch_file_pipe_timeout_set(switch_file_t *thepipe, switch_interval_time_t timeout); 1456 1457 1458 /** 1459 * stop the current thread 1460 * @param thd The thread to stop 1461 * @param retval The return value to pass back to any thread that cares 1462 */ 1463 SWITCH_DECLARE(switch_status_t) switch_thread_exit(switch_thread_t *thd, switch_status_t retval); 1464 1465 /** 1466 * block until the desired thread stops executing. 1467 * @param retval The return value from the dead thread. 1468 * @param thd The thread to join 1469 */ 1470 SWITCH_DECLARE(switch_status_t) switch_thread_join(switch_status_t *retval, switch_thread_t *thd); 1471 1472 /** 1473 * Return a human readable string describing the specified error. 1474 * @param statcode The error code the get a string for. 1475 * @param buf A buffer to hold the error string. 1476 * @bufsize Size of the buffer to hold the string. 1477 */ 1478 1479 SWITCH_DECLARE(char *) switch_strerror(switch_status_t statcode, char *buf, switch_size_t bufsize); 1480 1481 1482 1483 /** @} */ 1484 1485 SWITCH_END_EXTERN_C 1486 #endif 1487 /* For Emacs: 1488 * Local Variables: 1489 * mode:c 1490 * indent-tabs-mode:t 1491 * tab-width:4 1492 * c-basic-offset:4 1493 * End: 1494 * For VIM: 1495 * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet: 1496 */ 1497