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.

NotificationDescription
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.

ValueMeaning
FILEOP_ABORTAbort cabinet processing.
FILEOP_DOITExtract the current file.
FILEOP_SKIPSkip the current file.

 

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

ValueMeaning
NO_ERRORNo error was encountered, continue processing the cabinet.
ERROR_XXXAn 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.

 

 

Show: