Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:00 2009

## Asterisk developer's documentation

# app_curl.c File Reference

Curl - App to load a URL. More...

`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <curl/curl.h>`
`#include "asterisk.h"`
`#include "asterisk/lock.h"`
`#include "asterisk/file.h"`
`#include "asterisk/logger.h"`
`#include "asterisk/channel.h"`
`#include "asterisk/pbx.h"`
`#include "asterisk/cli.h"`
`#include "asterisk/options.h"`
`#include "asterisk/module.h"`

Include dependency graph for app_curl.c:

Go to the source code of this file.

## Data Structures

struct | MemoryStruct

## Functions

static char * | acf_curl_exec (struct ast_channel *chan, char *cmd, char *data, char *buf, size_t len)
static int | curl_exec (struct ast_channel *chan, void *data)
static int | curl_internal (struct MemoryStruct *chunk, char *url, char *post)
char * | description (void)
| Provides a description of the module.
char * | key ()
| Returns the ASTERISK_GPL_KEY.
int | load_module (void)
| Initialize the module.
static void * | myrealloc (void *ptr, size_t size)
int | unload_module (void)
| Cleanup all module structures, sockets, etc.
int | usecount (void)
| Provides a usecount.
static size_t | WriteMemoryCallback (void *ptr, size_t size, size_t nmemb, void *data)

## Variables

struct ast_custom_function | acf_curl
static char * | app = "Curl"
static char * | descrip
| LOCAL_USER_DECL
| STANDARD_LOCAL_USER
static char * | synopsis = "Load an external URL"
static char * | tdesc = "Load external URL"

## Detailed Description

Curl - App to load a URL.

Definition in file app_curl.c.

## Function Documentation

static char* acf_curl_exec | ( | struct ast_channel * | chan,
|  | char * | cmd,
|  | char * | data,
|  | char * | buf,
|  | size_t | len |
| ) |  |  | `[static]`

Definition at line 166 of file app_curl.c.

References ast_log(), ast_strdupa, ast_strlen_zero(), curl_internal(), free, LOCAL_USER_ACF_ADD, LOCAL_USER_REMOVE, LOG_ERROR, LOG_WARNING, MemoryStruct::memory, MemoryStruct::size, and strsep().

    00167 {
    00168    struct localuser *u;
    00169    char *info, *post_data=NULL, *url;
    00170    struct MemoryStruct chunk = { NULL, 0 };
    00171
    00172    *buf = '\0';
    00173
    00174    if (ast_strlen_zero(data)) {
    00175       ast_log(LOG_WARNING, "CURL requires an argument (URL)\n");
    00176       return buf;
    00177    }
    00178
    00179    LOCAL_USER_ACF_ADD(u);
    00180
    00181    info = ast_strdupa(data);
    00182    if (!info) {
    00183       ast_log(LOG_ERROR, "Out of memory\n");
    00184       LOCAL_USER_REMOVE(u);
    00185       return buf;
    00186    }
    00187
    00188    url = strsep(&info, "|");
    00189    post_data = info;
    00190
    00191    if (! curl_internal(&chunk, url, post_data)) {
    00192       if (chunk.memory) {
    00193          chunk.memory[chunk.size] = '\0';
    00194          if (chunk.memory[chunk.size - 1] == 10)
    00195             chunk.memory[chunk.size - 1] = '\0';
    00196
    00197          ast_copy_string(buf, chunk.memory, len);
    00198          free(chunk.memory);
    00199       }
    00200    } else {
    00201       ast_log(LOG_ERROR, "Cannot allocate curl structure\n");
    00202    }
    00203
    00204    LOCAL_USER_REMOVE(u);
    00205    return buf;
    00206 }

static int curl_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 118 of file app_curl.c.

References ast_log(), ast_strdupa, ast_strlen_zero(), curl_internal(), dep_warning, free, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_ERROR, LOG_WARNING, MemoryStruct::memory, pbx_builtin_setvar_helper(), MemoryStruct::size, and strsep().

Referenced by load_module().

    00119 {
    00120    int res = 0;
    00121    struct localuser *u;
    00122    char *info, *post_data=NULL, *url;
    00123    struct MemoryStruct chunk = { NULL, 0 };
    00124    static int dep_warning = 0;
    00125
    00126    if (!dep_warning) {
    00127       ast_log(LOG_WARNING, "The application Curl is deprecated.  Please use the CURL() function instead.\n");
    00128       dep_warning = 1;
    00129    }
    00130
    00131    if (ast_strlen_zero(data)) {
    00132       ast_log(LOG_WARNING, "Curl requires an argument (URL)\n");
    00133       return -1;
    00134    }
    00135
    00136    LOCAL_USER_ADD(u);
    00137
    00138    if ((info = ast_strdupa(data))) {
    00139       url = strsep(&info, "|");
    00140       post_data = info;
    00141    } else {
    00142       ast_log(LOG_ERROR, "Out of memory\n");
    00143       LOCAL_USER_REMOVE(u);
    00144       return -1;
    00145    }
    00146
    00147    if (! curl_internal(&chunk, url, post_data)) {
    00148       if (chunk.memory) {
    00149          chunk.memory[chunk.size] = '\0';
    00150          if (chunk.memory[chunk.size - 1] == 10)
    00151             chunk.memory[chunk.size - 1] = '\0';
    00152
    00153          pbx_builtin_setvar_helper(chan, "CURL", chunk.memory);
    00154
    00155          free(chunk.memory);
    00156       }
    00157    } else {
    00158       ast_log(LOG_ERROR, "Cannot allocate curl structure\n");
    00159       res = -1;
    00160    }
    00161
    00162    LOCAL_USER_REMOVE(u);
    00163    return res;
    00164 }

static int curl_internal | ( | struct MemoryStruct * | chunk,
|  | char * | url,
|  | char * | post |
| ) |  |  | `[static]`

Definition at line 93 of file app_curl.c.

References WriteMemoryCallback().

Referenced by acf_curl_exec(), and curl_exec().

    00094 {
    00095    CURL *curl;
    00096
    00097    curl = curl_easy_init();
    00098
    00099    if (!curl) {
    00100       return -1;
    00101    }
    00102
    00103    curl_easy_setopt(curl, CURLOPT_URL, url);
    00104    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);
    00105    curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)chunk);
    00106    curl_easy_setopt(curl, CURLOPT_USERAGENT, "asterisk-libcurl-agent/1.0");
    00107
    00108    if (post) {
    00109       curl_easy_setopt(curl, CURLOPT_POST, 1);
    00110       curl_easy_setopt(curl, CURLOPT_POSTFIELDS, post);
    00111    }
    00112
    00113    curl_easy_perform(curl);
    00114    curl_easy_cleanup(curl);
    00115    return 0;
    00116 }

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 242 of file app_curl.c.

    00243 {
    00244    return tdesc;
    00245 }

char* key | ( | void |  | ) |

Returns the ASTERISK_GPL_KEY.

This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of the GPL stated in the ASTERISK_GPL_KEY. Your module will not load if it does not return the EXACT message:

     char *key(void) {
             return ASTERISK_GPL_KEY;
     }

Returns:
  ASTERISK_GPL_KEY

Definition at line 254 of file app_curl.c.

References ASTERISK_GPL_KEY.

    00255 {
    00256    return ASTERISK_GPL_KEY;
    00257 }

int load_module | ( | void |  | ) |

Initialize the module.

This function is called at module load time. Put all code in here that needs to set up your module's hardware, software, registrations, etc.

Returns:
  This function should return 0 on success and non-zero on failure. If the module is not loaded successfully, Asterisk will call its unload_module() function.

Initialize the Agents module. This function is being called by Asterisk when loading the module. Among other thing it registers applications, cli commands and reads the cofiguration file.

Returns:
  int Always 0.

TE STUFF END

Definition at line 231 of file app_curl.c.

References ast_custom_function_register(), ast_register_application(), and curl_exec().

    00232 {
    00233    int res;
    00234
    00235    curl_global_init(CURL_GLOBAL_ALL);
    00236    res = ast_custom_function_register(&acf_curl);
    00237    res |= ast_register_application(app, curl_exec, synopsis, descrip);
    00238
    00239    return res;
    00240 }

static void* myrealloc | ( | void * | ptr,
|  | size_t | size |
| ) |  |  | `[static]`

Definition at line 69 of file app_curl.c.

References malloc, and realloc.

Referenced by WriteMemoryCallback().

    00070 {
    00071    /* There might be a realloc() out there that doesn't like reallocing
    00072       NULL pointers, so we take care of it here */
    00073    if (ptr)
    00074       return realloc(ptr, size);
    00075    else
    00076       return malloc(size);
    00077 }

int unload_module | ( | void |  | ) |

Cleanup all module structures, sockets, etc.

This is called at exit. Any registrations and memory allocations need to be unregistered and free'd here. Nothing else will do these for you (until exit).

Returns:
  Zero on success, or non-zero on error.

Definition at line 218 of file app_curl.c.

References ast_custom_function_unregister(), ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00219 {
    00220    int res;
    00221
    00222    res = ast_custom_function_unregister(&acf_curl);
    00223    res |= ast_unregister_application(app);
    00224
    00225    STANDARD_HANGUP_LOCALUSERS;
    00226    curl_global_cleanup();
    00227
    00228    return res;
    00229 }

int usecount | ( | void |  | ) |

Provides a usecount.

This function will be called by various parts of asterisk. Basically, all it has to do is to return a usecount when called. You will need to maintain your usecount within the module somewhere. The usecount should be how many channels provided by this module are in use.

Returns:
  The module's usecount.

Definition at line 247 of file app_curl.c.

References STANDARD_USECOUNT.

    00248 {
    00249    int res;
    00250    STANDARD_USECOUNT(res);
    00251    return res;
    00252 }

static size_t WriteMemoryCallback | ( | void * | ptr,
|  | size_t | size,
|  | size_t | nmemb,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 79 of file app_curl.c.

References MemoryStruct::memory, myrealloc(), and MemoryStruct::size.

Referenced by curl_internal().

    00080 {
    00081    register int realsize = size * nmemb;
    00082    struct MemoryStruct *mem = (struct MemoryStruct *)data;
    00083
    00084    mem->memory = (char *)myrealloc(mem->memory, mem->size + realsize + 1);
    00085    if (mem->memory) {
    00086       memcpy(&(mem->memory[mem->size]), ptr, realsize);
    00087       mem->size += realsize;
    00088       mem->memory[mem->size] = 0;
    00089    }
    00090    return realsize;
    00091 }

## Variable Documentation

struct ast_custom_function acf_curl

Definition at line 208 of file app_curl.c.

char* app = "Curl"`[static]`

Definition at line 46 of file app_curl.c.

char* descrip`[static]`

Definition at line 50 of file app_curl.c.

LOCAL_USER_DECL

Definition at line 62 of file app_curl.c.

STANDARD_LOCAL_USER

Definition at line 60 of file app_curl.c.

char* synopsis = "Load an external URL"`[static]`

Definition at line 48 of file app_curl.c.

char* tdesc = "Load external URL"`[static]`

Definition at line 44 of file app_curl.c.