MpScanStart function

Starts a scanning operation.

Syntax

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
);

Parameters

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.

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

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Header	MpClient.h
DLL	MpClient.dll

See also

MpErrorMessageFormat

MpHandleClose

MpManagerOpen

MPCALLBACK_DATA

MPSCAN_DATA

MPSCAN_RESOURCES

MPSCAN_TYPE