Description

The handler or web hook described here processes callbacks from the GrabzIt screenshot web service. The URL of this handler is passed to GrabzIt in the callBackURL parameter of the Save method. However this technique will only work if the handler is accessible via the Internet.

The following parameters are passed to the handler as GET parameters.

• id - the unique identifier of the screenshot, used by the GetResult method
• filename - the filename of the screenshot, automatically created by combining the screenshot's unique identifier with it's file extension
• message - any message due to an error caused during the processing of the screenshot
• customId - any custom id that was passed to the GrabzIt web service via the Save method
• format - the format of the screenshot, e.g "bmp8", "bmp16", "bmp24", "bmp", "csv", "gif", "jpg", "json", "pdf", "png", "tiff", "webp" or "xlsx"
• targeterror - if a 1 is returned then the capture contains a generic error, due to an issue caused by the capture target

If you want to block all access to the handler, except from GrabzIt then use this security technique.

Implementing a Callback Handler using MVC

To add a handler to a MVC project simply define a method with the following signature in a controller as shown in the SampleMVC project of the ASP.NET demo.

Then pass the URL of this method to GrabzIt so if this is in the Home controller then the callback URL could look something like: http://www.example.com/Home/Handler

public ActionResult Handler(string filename, string id, string message, string customId, string format, int targeterror)
{
    GrabzItClient grabzItClient = GrabzItClient.Create("Sign in to view your Application Key", "Sign in to view your Application Secret")%>");
    GrabzItFile file = grabzItClient.GetResult(id);
    file.Save(Server.MapPath("~/results/" + filename));

    return null;
}

Implementing a Callback Handler using Web Forms

The easiest way to implement a callback handler is to create a generic handler and inherit from GrabzIt.Handler class as shown below and then implement the Process method. This method captures five parameters passed to it from the GrabzIt service, including the unique id of the capture which is passed to the GetResult method.

This method then returns the capture, which is saved in the results directory. However if a null value is returned from the GetResult method this indicates that an error has occured.

public class OverridenHandler : GrabzIt.Handler
{
    protected override void Process(HttpContext context, string filename, string id, string message,
        string customId, string format, bool targetError)
    {
        GrabzItClient grabzIt = GrabzItClient.Create("Sign in to view your Application Key", "Sign in to view your Application Secret")%>");
        GrabzItFile file = grabzIt.GetResult(id);
        file.Save(context.Server.MapPath("~/results/" + filename));
    }
}

Other Techniques

While the above technique uses a generic handler, you can just as easily use a ASPX page to recieve the callback and download the capture. To do this just create your own ASPX page etc and then read the querystring parameters mentioned above. The most useful parameter is the id parameter, which can be used with the GetResult method to download the capture.