Creating a Cabinet Callback Routine

Because the Setup API does not supply a default cabinet callback routine, you need to supply a routine. The callback routine that the SetupIterateCabinet function requires must have the same form as those pointed to by FileCallback.

Following is the syntax that SetupIterateCabinet uses to send a notification to the callback routine.

MsgHandler(          //the specified callback routine
    Context,         //context used by the callback routine
    Notification,    //cabinet notification
    Param1,          //additional notification information
    Param2           //additional notification information
);

The Context parameter is a void pointer to a context variable or structure that can be used by the callback routine to store information that needs to persist between subsequent calls to the callback routine.

This context's implementation is specified by the callback routine, and it is never referenced or altered by SetupIterateCabinet.

The Notification parameter is an unsigned integer and will be one of the following values.

Notification	Description
SPFILENOTIFY_FILEEXTRACTED	The file has been extracted from the cabinet.
SPFILENOTIFY_FILEINCABINET	A file is encountered in the cabinet.
SPFILENOTIFY_NEEDNEWCABINET	The current file is continued in the next cabinet.

 

The final two parameters, Param1 and Param2, are also unsigned integers and contain additional information relevant to the notification. For more information about the notifications sent by SetupIterateCabinet, see Cabinet File Notifications.

A SP_FILE_NOTIFY_CALLBACK routine returns an unsigned integer. The cabinet callback routine should return one of the following values depending on the notification.

For the SPFILENOTIFY_FILEINCABINET notification, SetupIterateCabinet expects one of the following values to be returned by the callback routine.

Value	Meaning
FILEOP_ABORT	Abort cabinet processing.
FILEOP_DOIT	Extract the current file.
FILEOP_SKIP	Skip the current file.

 

For SPFILENOTIFY_NEEDNEWCABINET and SPFILENOTIFY_FILEEXTRACTED notifications, SetupIterateCabinet expects one of the following values to be returned by the callback routine.

Value	Meaning
NO_ERROR	No error was encountered, continue processing the cabinet.
ERROR_XXX	An error of the specified type occurred. The SetupIterateCabinet function will return FALSE, and the specified error code will be returned by a call to GetLastError.

 

If the callback routine returns FILEOP_DOIT, the routine must also provide a full target path. For more information see SPFILENOTIFY_FILEINCABINET.