MpScanStart function
Starts a scanning operation.
HRESULT WINAPI MpScanStart(
_In_ MPHANDLE hMpHandle,
_In_ MPSCAN_TYPE ScanType,
_In_ DWORD dwScanOptions,
_In_opt_ PMPSCAN_RESOURCES pScanResources,
_In_opt_ PMPCALLBACK_INFO pCallbackInfo,
_Out_ PMPHANDLE phScanHandle
);
-
hMpHandle [in]
-
Type: MPHANDLE
Handle to the malware protection manager interface. This handle is returned by the MpManagerOpen function.
-
ScanType [in]
-
Type: MPSCAN_TYPE
Specifies the type of scan. This parameter must be one of the members of the MPSCAN_TYPE enueration.
-
dwScanOptions [in]
-
Type: DWORD
Specifies various options for scanning operation.
Value Meaning - MPSCAN_OPTION_NONE
No specific option is requested. - MPSCAN_OPTION_ASYNC
The scan operation is to be asynchronous, where MpScanStart returns immediately after the successful initiation of scanning. (By default the scan operation is synchronous, meaning MpScanStart will return only after the scan is finished.) - MPSCAN_OPTION_PROGRESS
The caller is interested in receiving scan progress information via a callback. - MPSCAN_OPTION_LOWPRIORITY
Perform the scan with low priority. (By default the scan operation is performed with normal priority.) - MPSCAN_OPTION_PACKEDEXES
Scan packed executables for possible threats. - MPSCAN_OPTION_ARCHIVES
Scan archive contents for possible threats. Archives are files with extensions such as .zip, .cab, or .tar. - MPSCAN_OPTION_HEURISTICS
Enable heuristics-based scanning. This will scan for threats with detection type set to heuristics. - MPSCAN_OPTION_REPORTFRIENDLY
Report friendly items in a resource scan. This is intended for internal use only. - MPSCAN_OPTION_REPORTUNKNOWN
Report unknown items in a resource scan. This is intended for internal use only. - MPSCAN_OPTION_NOCONSOLIDATE
Do not consolidate scan results with global threat view. This is useful for a client (such as an email client) which wants to control cleaning UX by itself rather than allowing default anti-malware cleaning UX. This is intended for internal use only. -
pScanResources [in, optional]
-
Type: PMPSCAN_RESOURCES
A pointer to the scan resource information. This parameter must be NULL for a quick scan. This is an optional parameter for a full scan. For a resource scan this parameter must be specified with at least one resource information structure. To scan specific resources the caller must have GENERIC_READ permission for the resource. See MPSCAN_RESOURCES.
-
pCallbackInfo [in, optional]
-
Type: PMPCALLBACK_INFO
A pointer to the callback information used to feed the client with scan state changes (such as start and complete) and progress information. The MPCALLBACK_DATA passed back in the callback function reports actual scan state and progress-related information. The following is a list of possible callbacks:
Value Meaning - MPNOTIFY_SCAN_START
Scan operation started. - MPNOTIFY_SCAN_COMPLETE
Scan operation completed. Additional information is available via MPSCAN_DATA structure. - MPNOTIFY_SCAN_PAUSED
Scan operation is paused. - MPNOTIFY_SCAN_RESUMED
Scan operation resumed from pause. - MPNOTIFY_SCAN_CANCEL
Scan operation was cancelled. - MPNOTIFY_SCAN_PROGRESS
Scan progress information. Additional information (such as resource statistics) is available via MPSCAN_DATA structure. - MPNOTIFY_SCAN_ERROR
Scan error information for a specific resource. The specific resource information is available via MPSCAN_DATA structure. - MPNOTIFY_SCAN_INFECTED
Scan found an infected resource. Note that in most of the cases this will result in some threat reported at the end of the scan. Sometimes it may not materialize as a threat because of exclusions. Additional infected resource information is available via MPSCAN_DATA structure. - MPNOTIFY_SCAN_MEMORYSTART
Quick scan portion of the full scan has started. - MPNOTIFY_SCAN_MEMORYCOMPLETE
Quick scan portion of the full scan has completed. - MPNOTIFY_INTERNAL_FAILURE
Scan operation has encountered a generic failure. The hResult in MPCALLBACK_DATA has the specific error code. -
phScanHandle [out]
-
Type: PMPHANDLE
Returned scan handle which identifies the currently initiated scan. This handle can be used in subsequent function calls, such as to retrieve a scan result. The handle must be closed with the MpHandleClose function.
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.
Requirement | Value |
---|---|
Minimum supported client |
Windows 8 [desktop apps only] |
Minimum supported server |
Windows Server 2012 [desktop apps only] |
Header |
|
DLL |
|