RestParam

## RestParam RestParam — Name/value parameter data type with intelligent memory management |

## Synopsis

    enum                RestMemoryUse;
                        RestParam;
    RestParam *         rest_param_new_string               (const char *name,
                                                             RestMemoryUse use,
                                                             const char *string);
    RestParam *         rest_param_new_full                 (const char *name,
                                                             RestMemoryUse use,
                                                             gconstpointer data,
                                                             gsize length,
                                                             const char *content_type,
                                                             const char *filename);
    RestParam *         rest_param_new_with_owner           (const char *name,
                                                             gconstpointer data,
                                                             gsize length,
                                                             const char *content_type,
                                                             const char *filename,
                                                             gpointer owner,
                                                             GDestroyNotify owner_dnotify);
    gboolean            rest_param_is_string                (RestParam *param);
    const char *        rest_param_get_name                 (RestParam *param);
    const char *        rest_param_get_content_type         (RestParam *param);
    const char *        rest_param_get_file_name            (RestParam *param);
    gconstpointer       rest_param_get_content              (RestParam *param);
    gsize               rest_param_get_content_length       (RestParam *param);
    RestParam *         rest_param_ref                      (RestParam *param);
    void                rest_param_unref                    (RestParam *param);

## Description

## Details

### enum RestMemoryUse

    typedef enum {
      REST_MEMORY_STATIC,
      REST_MEMORY_TAKE,
      REST_MEMORY_COPY,
    } RestMemoryUse;

`REST_MEMORY_STATIC` | the memory block can be assumed to always exist for the lifetime of the parameter, RestParam will use it directly.
`REST_MEMORY_TAKE` | RestParam will take ownership of the memory block, and `g_free()` it when it isn't used.
`REST_MEMORY_COPY` | RestParam will make a copy of the memory block.

### RestParam

    typedef struct _RestParam RestParam;

### rest_param_new_string ()

    RestParam *         rest_param_new_string               (const char *name,
                                                             RestMemoryUse use,
                                                             const char *string);

A convience constructor to create a RestParam from a given UTF-8 string. The resulting RestParam will have a content type of "text/plain".

`name` : | the parameter name
`use` : | the RestMemoryUse describing how the memory can be used
`string` : | the parameter value
Returns : | a new RestParam.

### rest_param_new_full ()

    RestParam *         rest_param_new_full                 (const char *name,
                                                             RestMemoryUse use,
                                                             gconstpointer data,
                                                             gsize length,
                                                             const char *content_type,
                                                             const char *filename);

Create a new RestParam called `name` with `length` bytes of `data` as the value. `content_type` is the type of the data as a MIME type, for example "text/plain" for simple string parameters.

If the parameter is a file upload it can be passed as `filename`.

`name` : | the parameter name
`use` : | the RestMemoryUse describing how the memory can be used
`data` : | a pointer to the start of the data
`length` : | the length of the data
`content_type` : | the content type of the data
`filename` : | the original filename, or `NULL`
Returns : | a new RestParam.

### rest_param_new_with_owner ()

    RestParam *         rest_param_new_with_owner           (const char *name,
                                                             gconstpointer data,
                                                             gsize length,
                                                             const char *content_type,
                                                             const char *filename,
                                                             gpointer owner,
                                                             GDestroyNotify owner_dnotify);

Create a new RestParam called `name` with `length` bytes of `data` as the value. `content_type` is the type of the data as a MIME type, for example "text/plain" for simple string parameters.

If the parameter is a file upload it can be passed as `filename`.

When the RestParam is freed, it will call `owner_dnotify`, passing `owner` to it. This allows you to do something like this:

    1
    2
    3
    4
    5
    6
    7
    8
    GMappedFile *map = g_mapped_file_new (filename, FALSE, &error);
    RestParam *param = rest_param_new_with_owner ("media",
                                                  g_mapped_file_get_contents (map),
                                                  g_mapped_file_get_length (map),
                                                  "image/jpeg",
                                                  filename,
                                                  map,
                                                  (GDestroyNotify)g_mapped_file_unref);

`name` : | the parameter name
`data` : | a pointer to the start of the data
`length` : | the length of the data
`content_type` : | the content type of the data
`filename` : | the original filename, or `NULL`
`owner` : | pointer to an object that owns `data`
`owner_dnotify` : | a function to free/unref `owner` when the buffer is freed
Returns : | a new RestParam.

### rest_param_is_string ()

    gboolean            rest_param_is_string                (RestParam *param);

Determine if the parameter is a string value, i.e. the content type is "text/plain".

`param` : | a valid RestParam
Returns : | `TRUE` if the parameter is a string, `FALSE` otherwise.

### rest_param_get_name ()

    const char *        rest_param_get_name                 (RestParam *param);

Get the name of the parameter.

`param` : | a valid RestParam
Returns : | the parameter name.

### rest_param_get_content_type ()

    const char *        rest_param_get_content_type         (RestParam *param);

Get the MIME type of the parameter. For example, basic strings have the MIME type "text/plain".

`param` : | a valid RestParam
Returns : | the MIME type

### rest_param_get_file_name ()

    const char *        rest_param_get_file_name            (RestParam *param);

Get the original file name of the parameter, if one is available.

`param` : | a valid RestParam
Returns : | the filename if set, or `NULL`.

### rest_param_get_content ()

    gconstpointer       rest_param_get_content              (RestParam *param);

Get the content of `param`. The content should be treated as read-only and not modified in any way.

`param` : | a valid RestParam
Returns : | the content.

### rest_param_get_content_length ()

    gsize               rest_param_get_content_length       (RestParam *param);

Get the length of the content of `param`.

`param` : | a valid RestParam
Returns : | the length of the content

### rest_param_ref ()

    RestParam *         rest_param_ref                      (RestParam *param);

Increase the reference count on `param`.

`param` : | a valid RestParam
Returns : | the RestParam

### rest_param_unref ()

    void                rest_param_unref                    (RestParam *param);

Decrease the reference count on `param`, destroying it if the reference count reaches 0.

`param` : | a valid RestParam

## See Also

RestParams, RestProxyCall.