Developer Information

Extending mod_dims

Adding new ImageMagick commands to mod_dims is very
straighforward. Every mod_dims image manipulation operation is
implemented as a dims_operation_func function. This function
signature is defined as:

Function Signature
apr_status_t (dims_operation_func) (dims_request_rec *d, char *args, char **err)

Arguments
dims_request_rec *d
The current DIMS request information. This contains the MagickWand, request_rec and other information that may be useful. See mod_dims.h for a complete definition of this struct.
char *args
The args provided for this command. For example if /thumbnail/78x100/ was our operation/arguments, *args would be a string containing 78x100
char **err
This is used to pass back a static string error message in case of an error.

To extend mod_dims implement a new dims_operation_func in mod_dims_ops.c, declare it in mod_dims.h and finally register it in the dims_init function in mod_dims.c.

The dims_operation_func implementation should return one of the DIMS_ status codes defined mod_dims.h. If an error occurred the **err pointer can be set to a static error message that will be logged. Returning anything other than DIMS_SUCCESS@ will result in the NOIMAGE image being returned to the user.

Here is an example:

First implement our new function. For this example we will add the blur command.

apr_status_t
dims_blur_operation (dims_request_rec *d, char *args, char **err) {
    MagickStatusType flags;
    GeometryInfo geometry;

    flags = ParseGeometry(args, &geometry);
    if ((flags & RhoValue) == 0) {
        *err = "Parsing blur arguments failed";
        return DIMS_FAILURE;
    }                

    MAGICK_CHECK(MagickBlurImage(d->wand, geometry.rho, 3), d);

    return DIMS_SUCCESS;
}

The MAGICK_CHECK macro will check to make sure the operation was
successful and did not timeout. If either of those occur it will return an
appropriate status code to force a NOIMAGE image to be returned to the user.

Now declare this new function in mod_dims.h by adding it to the list of dim_operation_func.

dims_operation_func 
    dims_resize_operation,
    .
    .
    . 
    dims_blur_operation;

Finally register this new function in dims_init in the
mod_dims.c file. This lets the DIMS handler know to call the new
dims_blur_operation function when it encounters the blur operation
in the URL.

ops = apr_hash_make(p);
apr_hash_set(ops, "resize", APR_HASH_KEY_STRING, dims_resize_operation);
.
.
.
apr_hash_set(ops, "blur", APR_HASH_KEY_STRING, dims_blur_operation);

That’s it. Now the new operation blur can be used by a DIMS webservice call. For example:

http://127.0.0.1:8001/dims3/TEST/blur/25/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg