ICertView::SetRestriction

[This is preliminary documentation and subject to change.]

The SetRestriction method sets sorting and qualifying restrictions on a column.

[VB] SetRestriction(
  Long ColumnIndex, 
  Long SeekOperator,
  Long SortOrder,
  Variant pvarValue
);
 
[JAVA] SetRestriction(
  int ColumnIndex, 
  int SeekOperator,
  int SortOrder,
  Variant pvarValue
);
 
[C++] HRESULT SetRestriction(
  LONG ColumnIndex,          // in
  LONG SeekOperator,         // in
  LONG SortOrder,            // in
  VARIANT const *pvarValue   // in
);

Parameters

ColumnIndex

Must be a valid column index number for the view or a predefined column specifier. If ColumnIndex is not negative, this value represents the zero-based index of the column that is receiving the restriction.

If ColumnIndex is negative, it must be one of the values listed in the following table.

Value for ColumnIndex Action

CV_COLUMN_LOG_DEFAULT Restricts view to requests that have been resolved. A request is resolved if it has resulted in an issued certificate or a failed request; revoked certificates are considered resolved.

CV_COLUMN_LOG_FAILED_DEFAULT Restricts view to requests that have failed.

CV_COLUMN_QUEUE_DEFAULT Restricts view to requests that have not been resolved; if a request has resulted in either an issued certificate or a failed request, it will not be part of the view.

SeekOperator

Value for ColumnIndex	Action
CV_COLUMN_LOG_DEFAULT	Restricts view to requests that have been resolved. A request is resolved if it has resulted in an issued certificate or a failed request; revoked certificates are considered resolved.
CV_COLUMN_LOG_FAILED_DEFAULT	Restricts view to requests that have failed.
CV_COLUMN_QUEUE_DEFAULT	Restricts view to requests that have not been resolved; if a request has resulted in either an issued certificate or a failed request, it will not be part of the view.

This value is used with pvarValue and is used to define the data-query qualifier for the column. This value must be one of the values listed in the following table.

Value	Meaning
CVR_SEEK_EQ	Equal to
CVR_SEEK_LE	Less than or equal to
CVR_SEEK_LT	Less than
CVR_SEEK_GE	Greater than or equal to
CVR_SEEK_GT	Greater than

SortOrder

Specifies the sort order for this column, as defined in the following table.

Value	Meaning
CVR_SORT_ASCEND	Ascending
CVR_SORT_DESCEND	Descending
CVR_SORT_NONE	No sort order

pvarValue

Variant for the data query qualifier applied to this column. This value, along with the value of SeekOperator, determines which data is returned to the Certificate Server view.

Return Values

[C++] The return value is an HRESULT. A value of S_OK indicates success.

Remarks

The ICertView object maintains an array of restrictions, allowing multiple columns to contain restrictions. A column can contain more than one restriction. After the column restrictions are established, a call to the ICertView OpenView method will retrieve the data, with each column's restrictions used as part of the database query.

Before the ICertView SetRestriction method is called, it is necessary to call the ICertView OpenConnection method.

Example

// this example restricts the data,
// to rows that have RequestIDs greater than 5
// pCertView is pointer to ICertView
HRESULT    hr;
VARIANT    varRest;
LONG       nIndex;
BSTR       bstrCol = NULL;

// use one column in the result set
hr = pCertView->SetResultColumnCount( 1 );
if ( FAILED( hr ) )
{
    printf("Failed SetResultColumnCount - %x\n", hr );
    goto error;
}
// determine the column index for RequestID column
bstrCol = SysAllocString(TEXT("RequestID"));
hr = pCertView->GetColumnIndex( FALSE, bstrCol, &nIndex );
if ( FAILED( hr ) )
{
    printf("Failed GetColumnIndex - %x\n", hr );
    goto error;
}
// place this column into the result set
pCertView->SetResultColumn( nIndex );
// set a restriction on this index
VariantInit( &varRest);
varRest.vt = VT_I4;
varRest.lVal = 5;
// restrict view to requests with ID greater than 5
hr = pCertView->SetRestriction(nIndex,
                               CVR_SEEK_GT,
                               CVR_SORT_NONE,
                               &varRest);
if ( S_OK != hr )
    printf("Failed ICertView::SetRestriction - %x\n", hr);
else
    // Call OpenView, process rows, release resources, etc.
    // …
error:
// done processing, clear resources
VariantClear( &varRest );
if ( NULL != bstrCol )
    SysFreeString( bstrCol );

QuickInfo