BOOL RegisterEvent(
	UINT nEventId,
	WEBEVENTPROC lpEventProc,
	DWORD_PTR dwParam
);

The RegisterEvent method registers an event handler for the specified event.

Parameters

nEventId

An unsigned integer which specifies which event should be registered with the specified callback method. This parameter cannot be zero. The following values may be used:

Constant	Description
WEB_EVENT_CONNECT (1)	The connection to the storage server has been established and the session has been authenticated. This is the first event that occurs when initiating an operation to create or retrieve a storage object.
WEB_EVENT_DISCONNECT (2)	The connection to the storage server has been closed and the session is terminating. This is the last event that occurs after completing an operation to create or retrieve a storage object.
WEB_EVENT_READ (4)	The contents of an object is being read from the storage container. This event occurs only once after the operation has been initiated by the application. This event can also be generated if there is an error during the process of retrieving the object contents from the container.
WEB_EVENT_WRITE (8)	The contents of an object is being written to the storage container. This event occurs only once after the operation has been initiated by the application. This event can also be generated if there is an error during the process of submitting the object contents to the container.
WEB_EVENT_TIMEOUT (16)	The operation has exceeded the specified timeout period. The application may attempt to retry the operation or report an error to the user. This event typically indicates a connectivity problem with the storage server.
WEB_EVENT_CANCEL (32)	The operation has been canceled. This event occurs after the application calls the Cancel method while an object is being stored or retrieved.
WEB_EVENT_PROGRESS (64)	A storage operation is in progress. This event periodically occurs as the contents of a storage object is being read or written from the container. To retrieve information about the status of the operation, the application should register a handler for this event and call the GetTransferStatus method from within that handler.

lpEventProc

Specifies the procedure-instance address of the application defined callback method. For more information about the callback method, see the description of the WebEventProc callback method. If this parameter is NULL, the callback for the specified event is disabled.

dwParam

A user-defined integer value that is passed to the callback method specified by lpEventProc. If the application targets the x86 (32-bit) platform, this parameter must be a 32-bit unsigned integer. If the application targets the x64 (64-bit) platform, this parameter must be a 64-bit unsigned integer.

Return Value

If the method succeeds, the return value is non-zero. If the method fails, the return value is zero. To get extended error information, call the GetLastError method.

Remarks

The RegisterEvent method associates a static callback method with a specific event. The event handler is a WebEventProc function that is invoked when the event occurs. Arguments are passed to the method to identify the storage handle, 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.

Events are only generated as the result of a call to the GetFile, GetData, PutFile and PutData methods. Other storage methods will not generate event notifications.

This method is typically used to register an event handler that is invoked while the contents of a storage object is being transferred. The WEB_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 WEB_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.

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: cswebv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

Cancel, GetTransferStatus, UnregisterEvent, WebEventProc

Copyright © 2023 Catalyst Development Corporation. All rights reserved.