IProductCatalog::GuaranteedSpecificationSearch
Use this method to guarantee results when performing a specification search of a catalog.
Definition
HRESULT IProductCatalog::GuaranteedSpecificationSearch(VARIANT*pstrSearchHandle,VARIANTeClassTypeRequired,VARIANTlDesiredRecords,VARIANT*plTotalRecordsAvailable,VARIANT*pRSNewPropValuesList,VARIANTvrPropertiesRequired,_Recordset**ppRSSearchResults);
Parameters
pstrSearchHandle
[in, out]A VARIANT that contains the specification search handle.
eClassTypeRequired
[in, optional] A VARIANT that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.
lDesiredRecords
[in, optional] A VARIANT that contains the number of records desired.
plTotalRecordsAvailable
[out, optional] A pointer to a VARIANT used to return the total records available.
pRSNewPropValuesList
[out, optional] A Recordset used to return the new property values list.
vrPropertiesRequired
[in,optional] A VARIANT that contains the properties required in a comma delimited String.
ppRSSearchResults
[out, retval] A Recordset used to return the search results.
Return Values
This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.
Error Values
This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.
The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.
Constant | Value | Description |
S_FALSE | 0x00000001 | This value is returned when the pRSNewPropValuesList parameter is specified and:
|
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | 0x88980049 | The category you specified did not exist or was not specification searchable. |
Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.
Remarks
The pstrSearchHandle, plTotalRecordsAvailable, pRSNewPropValuesList, and ppRSSearchResults parameters contain valid data only if the property was accessed successfully.
This method is similar to the PerformSpecificationSearch method. The optional output parameter, pRSNewPropValuesList, is a single row recordset. This recordset contains one field for each searchable property for the products under the category specified in the BeginSpecificationSearch method. Each field contains a SAFEARRAY. The SAFEARRAY contains a set of distinct values for that property. The set is all the values in all the products that match the search clauses in the search handle. Only the properties that are marked as searchable are returned in the recordset. A property can be marked as searchable by setting the IncludeInSpecSearch attribute of that property to True.
This method guarantees that results will be returned from a specification search of the catalog by removing search constraints in the reverse order that they were added until a match is found. Therefore, remember to add constraints to a specification search in order of decreasing importance.
The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.
Note
- When field names begin with a number or contain spaces they must be enclosed in brackets. Data errors will occur if the field names are not formatted correctly. For example, "[123_Prop1],[123_ Prop2]". If the vrPropertiesRequired property is omitted then the data in all fields will be returned correctly.
The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.
Name | Value | Description |
cscCategoryClass | 1 | Requests category data. |
cscProductVariantClass | 2 | Requests product variant data. |
cscProductClass | 4 | Requests product data. |
cscProductFamilyClass | 8 | Requests product family data. |
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested. |
cscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested. |
CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical ORs , so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.
For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.
See Also
IProductCatalog::AddSpecificationSearchClause
IProductCatalog::PerformSpecificationSearch