Guidelines for creating a custom process

When creating a custom process dll you first create the project then define a client handle. Both are described below.

Creating a custom process DLL project in Visual Studio (2005)

1. Open Visual Studio.
2. Click File, point to New, then click Project.
3. Click Visual C++ on the left side of the window and select Win32 Project on the right side of the window.
4. Type a name for your project and click OK.
5. Click Application Settings in the left window.
6. Click DLL and check the Empty Project checkbox in the right window.
7. Click ‘Finish’.
8. Add a header and .cpp file if you have them, or create new ones.
9. Copy the .def file from one of the samples and paste it into your project directory. Rename the file and change the LIBRARY option to your project name.
10. Right-click the Project and click Properties.
11. Click on Linker, point to Input, then click Module Definition File and specify the .def file you just copied.
12. In the header, make sure to include the windows header file (windows.h) and the custom process interface (CustomProcess.h).
13. Before including any files, add the line "#define CustomProcess_exports". This signifies that the process is meant for export.

The client handle

The client handle is common to all sample custom processes and is how samples handle the issues of thread safety. Each client to the custom process DLL, must be uniquely identifiable by the DLL. This is because the functions of the DLL are called independently of each other and may be called simultaneously by different clients. Therefore, the DLL must be able to identify each client and use the properties particular to that client to do the processing. This can be handled in two ways:

1. The DLL generates a unique ID for each client and uses it as a client handle to identify different clients. This means that properties particular to different clients will have to be stored and accessed by the DLL in a proper manner.
2. The DLL creates a structure for each client. A pointer to this structure can then be directly passed as a client handle to each client. The members of the structure can be defined by the DLL. This is advantageous over the first method because it saves a lot of time when looking up particular properties pertaining to a client. The object can directly be cast and used.

The samples that come with ArcGIS Image Server use the second approach. Some of the common members of the client handle structure in the samples are described briefly below.

Standard members

AreaOfInterest* myAoi: A pointer to the Area Of Interest object provided by ArcGIS Image Server.

NVM* myProcessProps: A pointer to the ProcessProps object provided in CustomProcess_Create.

unsigned long myNumProps: Number of properties in the myProcessProps object.

CustomRasterInfo* myOutputRasterInfo: A pointer to the RasterInfo object provided in the CustomProcess_Initialize function.

unsigned long numOutElem: Number of elements in one row of the output.

char errorString[2048]: The string used to store error messages.

unsigned char* myOutputBuffer: The pointer to the output row buffer.

void* myCallbackObject: A pointer to the callback object used to call the callback functions with.

NVM* myProcessMetadata: A pointer to the internal metadata array used to store metadata about the process.

unsigned long myNumMetadata: Number of entries in the metadata array.

Members for processes using auxiliary rasters

char* myAuxRasterID: String containing the ID of the auxiliary raster.

CustomRasterInfo* myAuxRasterInfo: Pointer to the information of the auxiliary raster.

Function pointers for the callback functions

tGetRowfn myGetRowfn: Pointer to the GetRow callback function provided by ArcGIS Image Server.

tGetPropertyfn myGetPropertyfn: Pointer to the GetProperty callback function provided by ArcGIS Image Server.

tCreateAuxRasterfn myCreateAuxRasterfn: Pointer to the CreateAuxRaster callback function provided by ArcGIS Image Server.

tGetAuxRowfn myGetAuxRowfn: Pointer to the GetAuxRow callback function provided by ArcGIS Image Server.