IErrorRecords::AddErrorRecord

Adds a record to an OLE DB error object.

HRESULT AddErrorRecord (
   ERRORINFO *      pErrorInfo,
   DWORD            dwLookupID,
   DISPPARAMS *   pdispparams,
   IUnknown *         punkCustomError,
   DWORD            dwDynamicErrorID);

Parameters

pErrorInfo

[in]
A pointer to an ERRORINFO structure containing information about the error. This structure is allocated and freed by the consumer. For more information, see "Error Records" in Chapter 13.

dwLookupID

[in]
The value used by the provider's error lookup service in conjunction with the return code to identify the error description, Help file, and context ID for an error. This can be a provider-specific value, such as the dwMinor element of *pErrorInfo. It can also be a special value, IDENTIFIER_SDK_ERROR, that tells the implementation of IErrorInfo that is shipped with the OLE DB SDK to ignore the provider's lookup service and use the description supplied in the OLE DB SDK error resource DLL.

const DWORD IDENTIFIER_SDK_MASK  = 0xF000000;
const DWORD IDENTIFIER_SDK_ERROR = 0x1000000;

pdispparams

[in]
A pointer to the parameters for the error. This is a null pointer if there are no error parameters. The error parameters are inserted into the error text by the error lookup service. This structure is allocated and freed by the consumer. For more information, see "Error Parameters" in "Error Records" in Chapter 13.

punkCustomError

[in]
An interface pointer to the custom error object. This is a null pointer if there is no custom object for the error. For more information, see "OLE DB Error Objects" in Chapter 13.

dwDynamicErrorID

[in]
If the error lookup service uses static errors—that is, error information that is hard-coded in the lookup service—dwDynamicErrorID is zero.

If the error lookup service uses dynamic errors—that is, error information that is created at run time—dwDynamicErrorID is the ID of the error record. This ID is used to release the error information when the OLE DB error object is released. Although it is not required, it is more efficient for all error records in a single OLE DB error object to have the same dynamic error ID.

For more information, see "Error Lookup Services" in Chapter 13.

Return Code

S_OK
The method succeeded.

E_INVALIDARG
pErrorInfo was a null pointer.

E_OUTOFMEMORY
The OLE DB error object was unable to allocate sufficient memory with which to add a new record.

Comments

This method should be used only by providers; there are no reasons for consumers to use it.

Records are added to the top of the list. That is, the number of the newly added record is record 0 and the number of all other records is increased by 1.

AddErrorRecord adds a reference count on the custom error object. After adding a custom error object to a record in an OLE DB error object, the provider must call Release on all interface pointers it holds on that custom error object. This transfers ownership of the custom error object to the OLE DB error object. When it is released, the OLE DB error object will release all custom error objects.