ISessionProperties::GetProperties

  • Article

Returns the list of properties in the Session property group that are currently set on the session.

Syntax

HRESULT GetProperties (
   ULONG               cPropertyIDSets,
   const DBPROPIDSET   rgPropertyIDSets[],
   ULONG              *pcPropertySets,
   DBPROPSET         **prgPropertySets);

Parameters

  • cPropertyIDSets
    [in] The number of DBPROPIDSET structures in rgPropertyIDSets.

    If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns the values of all properties in the Session property group for which values have been set or defaults exist. It does not return the values of properties in the Session property group for which values have not been set and no defaults exist.

    If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported, the returned value of dwStatus in the returned DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of dwOptions is undefined.

  • rgPropertyIDSets
    [in] An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Session property group. The provider returns the values of information about the properties specified in these structures. If cPropertyIDSets is zero, this parameter is ignored.

    For information about the properties in the Session property group that are defined by OLE DB, see Session Properties in Appendix C. For information about the DBPROPIDSET structure, see DBPROPIDSET Structure.

  • pcPropertySets
    [out] A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Session property group. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other than DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero.

  • prgPropertySets
    [out] A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is returned for each property set that contains at least one property belonging to the Session property group. If cPropertyIDSets is not zero, one structure is returned for each property set specified in rgPropertyIDSets.

    If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets are returned in the same order as the DBPROPIDSET structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROP structures in the corresponding element of *prgPropertySets are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding elements of each array, the property IDs are the same.

    The provider allocates memory for the structures and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the structures. Before calling IMalloc::Free for *prgPropertySets, the consumer should call IMalloc::Free for the rgProperties element within each element of *prgPropertySets. The consumer must also call VariantClear for the vValue member of each DBPROP structure in order to prevent a memory leak in cases where the variant contains a reference type (such as a BSTR.) If *pcPropertySets is zero on output or if an error other than DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets is a null pointer on output.

    For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure.

Return Code

  • S_OK
    The method succeeded. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK.

  • DB_S_ERRORSOCCURRED
    No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to determine the properties for which values were not returned. ISessionProperties::GetProperties can fail to return properties for a number of reasons, including the following:

    • The property was not supported by the provider.

    • The property was not in the Session property group.

    • The property set was not supported by the provider. If cPropertyIDs in the DBPROPIDSET structure for the property set was zero, the provider cannot set dwStatus in the DBPROP structure because it does not know the IDs of any properties in the property set. Instead, it sets cProperties to zero in the DBPROPSET structure returned for the property set.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer.

    pcPropertySets or prgPropertySets was a null pointer.

    In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer.

  • E_OUTOFMEMORY
    The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures.

  • DB_E_ERRORSOCCURRED
    Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no longer needs the information.

See Also

Reference

IDBProperties::GetPropertyInfo

ISessionProperties::SetProperties