fTWUCallback

The fTWUCallback typedef defines the callback function prototype used as a general event/progress callback. The actual callback function may have any valid C/C++ name, but it must follow the prototype defined by the fTWUCallback typedef.

typedef URESULT (*fTWUCallback)(
    TWUHANDLE hSession,
    int nEventCode,
    const TCHAR *pszEventMsg,
    UINT64 ulProgress,
    UINT64 ulTotal,
    LPARAM lCookie
);

Delphi version:

type fTWUCallback = function(
    hSession: TWUHANDLE;
    nEventCode: Integer;
    pszEventMessage: PTCHAR;
    ulProgress: UINT64;
    ulTotal: UINT64;
    lCookie: LPARAM
): URESULT;

Parameters

hSession

[Input] Handle to an open TWU session.

nEventCode

[Input] One of the event codes as defined in Callback events below.

pszEventMsg

[Input] Pointer to a 0-terminated string that describes the event in a user-friendly way. Your callback function may use this string for display in its user interface.

From release 3.3.2435 onwards, this parameter may contain additional strings that provide raw information about the event, for example a URL or file path. Use the TWUGetEventArg function to access the additional information, as in TWUGetEventArg(pszEventMsg, 0). See Callback events below for a per-event list of additional information.

ulProgress

[Input] Amount of progress made towards the total size given by ulTotal, or 0 if no progress amount is available or applicable. Your callback function may use this value to update a progress bar or something similar.

ulTotal

[Input] Total size or amount of work to do in the current operation, or 0 if the total is not available. During download progress events (TWU_CBEVENT_DOWNLOAD_PROGRESS, see below), both ulProgress and ulTotal are expressed in bytes, if the sizes are available.

lCookie

[Input] User-defined value that was passed in to TWUOpenSession, TWUOpenUpdateURL, or TWURegisterCallback. You can use this cookie to pass additional information to the callback function.

Return value

If the function succeeds, it must return ERROR_SUCCESS (0) to continue the operation. If it fails or if you want to terminate the operation for some reason, the function must return a nonzero Win32 error code. In that case, the operation will be terminated as soon as possible.

Note: Some events ignore the return code; see the table below.

Callback events

The following table defines the callback events passed to the callback function. Events marked * ignore the callback's return code. Unless otherwise noted, the event has no additional arguments.

Name	Value	Description and arguments
TWU_CBEVENT_SESSION_OPENING	0	A new TWU session is about to open.
TWU_CBEVENT_SESSION_OPENERROR*	1	An error occurred while opening the TWU session.
TWU_CBEVENT_SESSION_OPENED	2	The TWU session has opened.
TWU_CBEVENT_SESSION_CLOSING*	3	The TWU session is about to close.
TWU_CBEVENT_SESSION_CLOSED*	4	The TWU session has closed.
TWU_CBEVENT_CONNECTING	5	TWU is attempting to connect to the Internet.
TWU_CBEVENT_CONNECTERROR*	6	An error occurred while connecting to the Internet.
TWU_CBEVENT_CONNECTED	7	TWU has connected to the Internet.
TWU_CBEVENT_URL_OPENING	8	A download connection is about to be opened. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_URL_OPENERROR*	9	An error occurred while opening the download connection. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_URL_OPENED	10	The download connection has been opened. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_URL_CLOSED*	11	The download connection has been closed. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_FILE_OPENING	12	A local file to receive the download is about to be opened. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_FILE_OPENERROR*	13	An error occurred while opening a local file. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_FILE_OPENED	14	The local file has been opened. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_FILE_CLOSED*	15	The local file has been closed. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_FILE_DELETING	16	A local file is about to be deleted. Argument 0=File path to be deleted
TWU_CBEVENT_FILE_DELETED	17	A local file has been deleted. Argument 0=File path that was deleted
TWU_CBEVENT_FILE_DELETEERROR	18	An error occurred while deleting a local file. Argument 0=File path that could not be deleted
TWU_CBEVENT_DOWNLOAD_START	19	The download process is about to start. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_DOWNLOAD_END	20	The download process has been successfully completed. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_DOWNLOAD_READERROR*	21	An error occurred while downloading data from the Internet. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_DOWNLOAD_WRITEERROR*	22	An error occurred while writing data to a local file. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_DOWNLOAD_PROGRESS	23	The next buffer full of data has been downloaded and saved. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_PACKAGE_ENUM	24	A package is about to be processed. Argument 0=Package name
TWU_CBEVENT_PROCESS_STARTING	25	An installation program is about to be started. Argument 0=Path to executable program
TWU_CBEVENT_PROCESS_STARTED	26	An installation program has been started. Argument 0=Path to executable program
TWU_CBEVENT_PROCESS_ERROR*	27	An error occurred while starting an installation program. Argument 0=Path to executable program
TWU_CBEVENT_PROCESS_TERMINATED*	28	An synchronous installation program terminated. Argument 0=Path to executable program
TWU_CBEVENT_PIF_STARTPARSE	29	Parsing of the downloaded PIF is about to start. Argument 0=Path to the local PIF copy
TWU_CBEVENT_PIF_ENDPARSE	30	Parsing of the downloaded PIF is complete. Argument 0=Path to the local PIF copy
TWU_CBEVENT_PIF_STARTPACKAGE	31	Parsing of a package section in the downloaded PIF is about to start. Argument 0=Path to the local PIF copy Argument 1=Package section name
TWU_CBEVENT_PIF_ENDPACKAGE	32	Parsing of a package section in the downloaded PIF is completed. Argument 0=Path to the local PIF copy Argument 1=Package section name
TWU_CBEVENT_SIGNATURE_VALID	33	The downloaded package file has a valid signature. This event is only produced if the TWU_DWNF_VERIFYTRUST download flag is specified in the call to TWUGetPackageInstaller and the signature is valid, or the user elected to accept an unsigned package. Argument 0=Download URL Argument 1=Local file path
TWU_CBEVENT_SIGNATURE_ERROR	34	The downloaded package file does not have a valid signature. This event is only produced if the TWU_DWNF_VERIFYTRUST download flag is specified in the call to TWUGetPackageInstaller and the signature is invalid or missing, and the user did not accept the package. Argument 0=Download URL Argument 1=Local file path