Defining the Filter Function (Embedded SQL Guide)
Go Up to Writing an External Blob Filter (Embedded SQL Guide)
When writing your filter, you must include an entry point, known as a filter function, in the declaration section of the program. InterBase calls the filter function when your application performs a Blob access operation. All communication between InterBase and the filter is through the filter function. The filter function itself may call other functions that comprise the filter executable.
Declare the name of the filter function and the name of the filter executable with the ENTRY_POINT and MODULE_NAME parameters of the DECLARE FILTER statement.
A filter function must have the following declaration calling sequence:
filter_function_name(short action, isc_blob_ctl control);
The parameter, <action>, is one of eight possible action macro definitions and the parameter, <control>, is an instance of the isc_blob_ctl Blob control structure, defined in the InterBase header file ibase.h. These parameters are discussed later in this chapter.
The following listing of a skeleton filter declares the filter function, jpeg_filter:
#include <ibase.h>
#define SUCCESS 0
#define FAILURE 1
ISC_STATUS jpeg_filter(short action, isc_blob_ctl control)
{
ISC_STATUS status = SUCCESS;
switch (action)
{
case isc_blob_filter_open:
. . .
break;
case isc_blob_filter_get_segment:
. . .
break;
case isc_blob_filter_create:
. . .
break;
case isc_blob_filter_put_segment:
. . .
break;
case isc_blob_filter_close:
. . .
break;
case isc_blob_filter_alloc:
. . .
break;
case isc_blob_filter_free:
. . .
break;
case isc_blob_filter_seek:
. . .
break;
default:
status = isc_uns_ext /* unsupported action value */
. . .
break;
}
return status;
}
InterBase passes one of eight possible actions to the filter function, jpeg_filter(), by way of the <action> parameter, and also passes an instance of the Blob control structure, isc_blob_ctl, by way of the parameter <control>.
The ellipses (…) in the previous listing represent code that performs some operations based on each action, or event, that is listed in the case statement. Each action is a particular event invoked by a database operation the application might perform. For more information, see Programming Filter Function Actions.
The isc_blob_ctl Blob control structure provides the fundamental data exchange between InterBase and the filter. For more information on the Blob control structure, see Defining the Blob Control Structure.
Topics
- Defining the Blob Control Structure
- Programming Filter Function Actions
- Testing the Function Return Value