Notifications (Setup API)

Notifications are values that a setup function sends to a callback routine to specify a state or event. Two parameters, Param1 and Param2, are sent with the notification, and contain additional information relevant to the notification.

The callback routine processes the notification and returns an unsigned integer to the setup function. Depending on the setup function, you can use this value to specify an operation or user selection, or you may ignore it.

The setup functions send notifications to callback routines using the following syntax.

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

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

Because the callback routine specifies the context's implementation, and it is never referenced or altered by the setup functions, the context is not documented in the reference material for the notification messages that follow.

The Notification parameter specifies an unsigned integer value for an event or state that causes the setup function to call the callback routine.

Param1 and Param2 are optional parameters that can contain additional information relevant to the notification. These parameters are unsigned integers. If Param1 or Param2 return information that is not an unsigned integer, it is cast to an unsigned integer and must be recast to its original data type before it can be used by the callback routine.

Note

The following notifications represent every notification used by the setup functions. Individual functions use a subset of these notifications. In other words, not every notification is used by every function.

 

The following notifications are used by the setup functions.

Notification	Description
SPFILENOTIFY_COPYERROR	An error occurred during a file copy operation.
SPFILENOTIFY_DELETEERROR	An error occurred during a file deletion operation.
SPFILENOTIFY_ENDCOPY	A file copy operation has ended.
SPFILENOTIFY_ENDDELETE	A file deletion operation has ended.
SPFILENOTIFY_ENDQUEUE	The queue has finished committing.
SPFILENOTIFY_ENDREGISTRATION	The registration or unregistration of the file has finished.
SPFILENOTIFY_ENDRENAME	A file rename operation has ended.
SPFILENOTIFY_ENDSUBQUEUE	A subqueue (either copy, rename or delete) has ended.
SPFILENOTIFY_FILEEXTRACTED	The file has been extracted from the cabinet.
SPFILENOTIFY_FILEINCABINET	A file is encountered in the cabinet.
SPFILENOTIFY_FILEOPDELAYED	The file was in use, and the current operation has been delayed until the system is rebooted.
SPFILENOTIFY_LANGMISMATCH	The language of the current operation does not match the system language.
SPFILENOTIFY_NEEDMEDIA	New source media is required.
SPFILENOTIFY_NEEDNEWCABINET	The current file is continued in the next cabinet.
SPFILENOTIFY_QUEUESCAN	A node in the file queue has been scanned.
SPFILENOTIFY_QUEUESCAN_EX	A node in the file queue has been scanned.
SPFILENOTIFY_QUEUESCAN_SIGNERINFO	A node in the file queue has been scanned.
SPFILENOTIFY_RENAMEERROR	An error occurred during a file rename operation.
SPFILENOTIFY_STARTCOPY	A file copy operation has started.
SPFILENOTIFY_STARTDELETE	A file delete operation has started.
SPFILENOTIFY_STARTQUEUE	The queue has started to commit.
SPFILENOTIFY_STARTREGISTRATION	The registration or unregistration of the file has started.
SPFILENOTIFY_STARTRENAME	A file rename operation has started.
SPFILENOTIFY_STARTSUBQUEUE	A subqueue (either copy, rename or delete) has started.
SPFILENOTIFY_TARGETEXISTS	A copy of the specified file already exists on the target.
SPFILENOTIFY_TARGETNEWER	A newer version of the specified file exists on the target.