IErrorRecords::AddErrorRecord

Adds a record to an OLE DB error object.

Syntax

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.

  • 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 data access IerrorInfo implementation to ignore the provider's lookup service and use the description supplied in the data access 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.

  • 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.

  • 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.

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.

IErrorRecords::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.

See Also

Reference

IErrorRecords::GetBasicErrorInfo

IErrorRecords::GetCustomErrorObject

IErrorRecords::GetErrorParameters