3.38.4.11 IUpdateSearcher::Search (Opnum 20)

The IUpdateSearcher::Search (opnum 20) method performs an update search.

 HRESULT Search(
   [in] BSTR criteria,
   [out, retval] ISearchResult** retval
 );

criteria: A string specifying criteria that updates are required to meet in order to be returned in the search results.

The server MUST support criteria specified by the following ABNF grammar.

  
 criteria = andgroup *[1,*WSP "or" 1,*WSP andgroup] /
  
 andgroup = andgroup *[1,*WSP "and" 1,*WSP andgroup] / "(" *WSP andgroup *WSP ")" / criterion
  
 criterion = propertyname *WSP operator *WSP value / "(" *WSP criterion *WSP ")"
  
 propertyname = "Type" / "DeploymentAction" / "IsAssigned" / 
    "AutoSelectOnWebSites" / "BrowseOnly" / "UpdateID" / "RevisionNumber" /
    "CategoryIDs" / "IsInstalled" / "IsHidden" /  "IsPresent" /
    "RebootRequired"
  
 operator = "=" / "!=" / "contains"
  
 value = string / integer
  
 string = "'" *CHAR "'"
  
 integer = ["-"] 1*DIGIT

The CHAR and DIGIT production rules are specified in [RFC5234] section B.1.

Integer values MUST be specified in base 10. String values MUST be escaped (using the IUpdateSearcher::EscapeString (opnum 18) method) before being enclosed in single quotation marks, as specified by the preceding grammar. String comparisons MUST be case-insensitive.

The server MUST support the following update properties with the given operators and value types.

Update property name	Operators supported	Value type	Description
Type	=, !=	String	Compares the update's type to that given.
DeploymentAction	=	String	Finds updates with the given deployment action. If this criterion is not specified, the search operation MUST return only updates with a DeploymentAction of "Installation".
IsAssigned	=	Integer MUST be 0 or 1	The value is treated as a Boolean. The value determines whether the search operation finds updates that are intended for processing by an automatic update agent.
AutoSelectOnWebsites	=	Integer MUST be 0 or 1	The value is treated as a Boolean. The value determines whether the search operation finds updates that are intended to be automatically selected from web user interfaces.
BrowseOnly	=	Integer MUST be 0 or 1	The value is treated as a Boolean. The value determines whether the search operation finds updates that are not intended for processing by an automatic update agent.
UpdateID	=, !=	String	Compares the update's ID to that given.
RevisionNumber	=	Integer	Finds updates with the given revision number.
CategoryIDs	Contains	String	Finds updates belonging to the given category.
IsInstalled	=	Integer MUST be 0 or 1	The value is treated as a Boolean. The value determines whether the search operation finds updates that are installed.
IsHidden	=	Integer MUST be 0 or 1	The value is treated as a Boolean. The value determines whether the search operation finds updates that have been hidden by a user.
IsPresent	=	Integer MUST be 0 or 1	The value is treated as a Boolean. The value determines whether the search operation finds updates that are present, that is, updates that have been installed for one or more products.
RebootRequired	=	Integer MUST be 0 or 1	The value is treated as a Boolean. The value determines whether the search operation finds updates that currently require a reboot to complete installation or uninstallation.

retval: An ISearchResult instance with the results of the search.

Return Values: The method MUST return information in an HRESULT data structure. The severity bit in the structure identifies the following conditions:

• If the severity bit is set to 0, the method completed successfully.

• If the severity bit is set to 1, the method failed and encountered a fatal error.

If the criteria string cannot be parsed by the search criteria grammar specified preceding, the method MUST return an error.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].

The server SHOULD trigger the update agent to perform an update search through an implementation-dependent<41> interface.

The update search MUST be restricted to updates meeting the criteria specified. If the criteria parameter is NULL or the empty string, the server SHOULD trigger the update agent to use default search criteria, as defined by the update agent.

If the value of the CanAutomaticallyUpgradeService ADM element is VARIANT_TRUE, the search operation MAY automatically upgrade the update agent.

If the value of the IncludePotentiallySupersededUpdates ADM element is VARIANT_TRUE, the search operation results SHOULD include updates superseded by other updates in the search results. Otherwise, the search operation results SHOULD NOT include updates superseded by other updates in the search results.

If the value of the Online ADM element is VARIANT_TRUE, the search operation SHOULD go online.

The following table specifies the update server against which the search operation SHOULD be performed.

If the value of the IgnoreDownloadPriority ADM element is VARIANT_TRUE, the search operation SHOULD ignore the download priority of updates when computing update supersedence.

The following table specifies the set of updates for which the search operation SHOULD be performed.