MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 14: Properties


 

DBPROPINFO Structure

Providers use DBPROPINFO structures to return information about properties. An array of DBPROPINFO values is passed in a DBPROPINFOSET structure.

The DBPROPINFO structure is defined as follows:

typedef struct tagDBPROPINFO {
   LPOLESTR       pwszDescription;
   DBPROPID       dwPropertyID;
   DBPROPFLAGS    dwFlags;
   VARTYPE        vtType;
   VARIANT        vValues;
} DBPROPINFO;

The elements of this structure are described in the following table.

Element Description
pwszDescription A text description of the property. For properties defined by OLE DB, this must be the description listed for the property in Appendix C, "OLE DB Properties." This property description is used to construct connection strings and must meet all of the following requirements in order to work correctly with the Data Source Locator:
  • All property descriptions must be unique.

  • All property descriptions are NOT to be localized.

  • Property descriptions must not contain the equal sign or single or double quotation marks. However, they may contain semicolons.

All OLE DB properties, including provider-specific properties, must have non-NULL descriptions.
dwPropertyID The ID of the property.
dwFlags A bitmask that describes the property, such as the group it belongs to and whether it can be read from or written to. For more information, see "DBPROPFLAGS Enumerated Type," earlier in this chapter.

If the property is not supported, this is DBPROPFLAGS_NOTSUPPORTED. In this case, pwszDescription is set to NULL, and vtType and vValues are set to indicate VT_EMPTY.
vtType The type indicator of the property. This is used in the vt element of the VARIANT structure passed in the DBPROP structure.
vValues A list of the supported values for the property. Normally this list is returned only if the property can be set and if one of the following conditions apply:
  • The property type is an integer, and the possible values of the property are an enumerated type.

  • The property type is an integer whose bits are to be read as a bitmask, and all supported bits are set.

  • The property type is a string and the possible values form a small, well-defined set. The definition of a small, well-defined set is provider-specific. For example, the provider might return the list of possible authentication services (DBINIT_OPT_AUTH_INTEGRATED property) but not the list of possible user IDs (DBINIT_OPT_AUTH_USERID property).

If this list is returned, the vt element in vValues is VT_ARRAY combined with the type indicator returned in vtType. If this list is not returned, the vt element is VT_EMPTY. The consumer must free any memory pointed to by elements of vValues by calling the COM function VariantClear.