The RegisterEvent method associates a
callback function with a specific event. The event handler is an
HttpEventProc function that is invoked when the event
occurs. Arguments are passed to the function to identify the client
session, the event type and the user-defined value specified when the
event handler is registered. If the event occurs because of an error
condition, the error code will be provided to the handler.
This method is typically used to register an event handler
that is invoked while a resource is being retrieved or data is being
submitted to the server. The HTTP_EVENT_PROGRESS event will only be generated
periodically during the transfer to ensure the application is not
flooded with event notifications. It is guaranteed that at least one
HTTP_EVENT_PROGRESS notification will occur at the beginning of the
transfer, and one at the end of the transfer when it has completed.
The callback function specified by the lpEventProc
parameter must be declared using the __stdcall
calling convention. This ensures the arguments passed to the event
handler are pushed on to the stack in the correct order. Failure to
use the correct calling convention will corrupt the stack and cause
the application to terminate abnormally.
The dwParam parameter is commonly used to identify the
class instance which is associated with the event that has occurred.
Applications will cast the this pointer to a
DWORD_PTR value when calling this function, and then the event handler
will cast it back to a pointer to the class instance. This gives the
handler access to the class member variables and methods.