MpUpdateStart function

Starts a signature update operation.

Syntax

HRESULT WINAPI MpUpdateStart(
  _In_     MPHANDLE         hMpHandle,
  _In_     DWORD            dwUpdateOptions,
  _In_opt_ PMPCALLBACK_INFO pCallbackInfo,
  _Out_    PMPHANDLE        phUpdateHandle
);

Parameters

hMpHandle [in]

Type: MPHANDLE

Handle to the malware protection manager interface. This handle is returned by the MpManagerOpen function.

dwUpdateOptions [in]

Type: DWORD

Specifies the option for the signature update operation. It can be one of the following values:

Value	Meaning
MPUPDATE_OPTION_NONE	No specific option is requested.
MPUPDATE_OPTION_ASYNC	The update operation is to be asynchronous, where MpUpdateStart returns immediately after the successful initiation of the signature update. (By default the update operation is synchronous, meaning MpUpdateStart will return only after the signature update is finished.)
MPUPDATE_OPTION_PROGRESS	The caller is interested in receiving signature update progress information via a callback.
MPUPDATE_OPTION_HTTP	The signature update is performed by downloading the full signature package from the Microsoft security portal site. This can be used as a fallback option if the client is experiencing a signature download problem via Microsoft Update.
MPUPDATE_OPTION_UNC	Performs signature update using direct download from UNC shares.
MPUPDATE_OPTION_MANAGED	Performs signature update using the Managed Service WSUS.
MPUPDATE_OPTION_UNMANAGED	Performs signature update using the Unmanaged Service MU/WU.

pCallbackInfo [in, optional]

Type: PMPCALLBACK_INFO

A pointer to the callback information used to feed the client with signature update state changes (such as start and complete) and progress information. The MPCALLBACK_DATA passed back in the callback function reports actual update state and progress-related information. The following is a list of possible callbacks:

Value	Meaning
MPNOTIFY_SIGUPDATE_START	Update operation started.
MPNOTIFY_SIGUPDATE_COMPLETE	Update operation completed.
MPNOTIFY_SIGUPDATE_SEARCH_START	Search for updates started.
MPNOTIFY_SIGUPDATE_SEARCH_COMPLETE	Search for updates completed. Additional information is available via MPSIGUPDATE_DATA structure.
MPNOTIFY_SIGUPDATE_DOWNLOAD_START	Download for update started.
MPNOTIFY_SIGUPDATE_DOWNLOAD_PROGRESS	Download progress information. Additional information is available via MPSIGUPDATE_DATA structure.
MPNOTIFY_SIGUPDATE_DOWNLOAD_COMPLETE	Download for update complete. Additional information is available via MPSIGUPDATE_DATA structure.
MPNOTIFY_SIGUPDATE_INSTALL_START	Installation of update started.
MPNOTIFY_SIGUPDATE_INSTALL_PROGRESS	Installation progress information. Additional information is available via MPSIGUPDATE_DATA structure.
MPNOTIFY_SIGUPDATE_INSTALL_COMPLETE	Installation of update completed. Additional information is available via MPSIGUPDATE_DATA structure.
MPNOTIFY_SIGUPDATE_REQUEST_PROCESSED	The antimalware service processed a signature update request. Failure or success is indicated by hResult in MPCALLBACK_DATA.
MPNOTIFY_SIGUPDATE_REBOOT_REQUIRED	Requires reboot to complete the update operation. Failure or success is indicated by hResult in MPCALLBACK_DATA.
MPNOTIFY_INTERNAL_FAILURE	Signature update operation has encountered a generic failure. The hResult in MPCALLBACK_DATA has the specific error code.

phUpdateHandle [out]

Type: PMPHANDLE

Returned update handle which identifies the currently initiated signature update operation. This handle can be used in subsequent function calls, such as to control the signature update operation. The handle must be closed with the MpHandleClose function.

Return value

Type: HRESULT

If the function succeeds the return value is S_OK.

If the function fails then the return value is a failed HRESULT code. The caller can use the MpErrorMessageFormat function to get a generic description of the error message.

Requirements

See also

MpErrorMessageFormat

MpHandleClose

MpManagerOpen

MPCALLBACK_DATA

MPSIGUPDATE_DATA