MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 7: BLOBs and COM Objects
The following sections discuss how to bind, get, and set BLOB data using storage objects.
To bind BLOB data as a storage object, a consumer creates an accessor that includes a binding to the BLOB column. The consumer will perform the following actions:
If the consumer specifies an interface that is not supported by the provider, the provider returns E_NOINTERFACE when it validates the accessor. This can occur in IAccessor::CreateAccessor or in a method that uses the accessor, such as IRowset::GetData. To determine which interfaces are supported by the provider, the consumer calls IDBProperties::GetProperties with the DBPROP_STRUCTUREDSTORAGE property.
If the consumer specifies any invalid or unsupported flags, the provider returns DB_E_BADSTORAGEFLAG when it validates the accessor. This can occur in IAccessor::CreateAccessor or in a method that uses the accessor, such as IRowset::GetData.
To get BLOB data by using a storage object, a consumer will perform the following actions:
The provider creates a storage object over the BLOB's data and returns a pointer to the requested storage interface (ISequentialStream, IStream, IStorage, or ILockBytes) on this object. If the provider supports only a single open storage object at a time and another storage object is open, the method returns a status of DBSTATUS_E_CANTCREATE for the column.
If the consumer calls IRowset::GetData, IRowsetRefresh::GetLastVisibleData, or IRowsetUpdate::GetOriginalData multiple times for the BLOB column, the provider returns distinct pointers to storage interfaces on each call. This is similar to opening a file multiple times and returning a different file handle each time. It is the consumer's responsibility to call Release on each of these storage interfaces separately.
For example, the following code binds a BLOB column and uses ISequentialStream::Read to get the data:
#include<oledb.h>
IRowset * pIRowset;
IAccessor * pIAccessor;
IMalloc * pIMalloc;
int main() {
// Assume the consumer has a pointer (pIRowset) that
// points to the rowset. Create an accessor for the
// BLOB column. Assume it is column 1.
HACCESSOR hAccessor;
DBBINDSTATUS rgStatus[1];
DBOBJECT ObjectStruct;
DBBINDING rgBinding[1] = {
1, // Column 1
0, // Offset to data
0, // Ignore length field
sizeof(IUnknown *), // Offset to status field
NULL, // No type info
&ObjectStruct, // Object structure
NULL, // Ignore binding extensions
DBPART_VALUE|DBPART_STATUS, // Bind value and status
DBMEMOWNER_CLIENTOWNED, // Consumer owned memory
DBPARAMIO_NOTPARAM, // Not a parameter
0, // Ignore size of data
0, // Reserved
DBTYPE_IUNKNOWN, // Type DBTYPE_IUNKNOWN
0, // Precision not applicable
0 // Scale not applicable
} ;
ISequentialStream * pISequentialStream;
// Set the elements in the object structure so that the
// provider creates a readable ISequentialStream object over
// the column. The consumer will read data from this object.
ObjectStruct.dwFlags = STGM_READ;
ObjectStruct.iid = IID_ISequentialStream;
pIRowset->QueryInterface(IID_IAccessor, (void**) &pIAccessor);
pIAccessor->CreateAccessor(DBACCESSOR_ROWDATA, 1, rgBinding,
sizeof(IUnknown *) + sizeof(ULONG), &hAccessor, rgStatus);
pIAccessor->Release();
// Allocate memory for the returned pointer and the
// status field. The first sizeof(IUnknown*) bytes are
// for the pointer to the object, and the next sizeof(ULONG)
// bytes are for the status.
void * pData = pIMalloc->Alloc(sizeof(IUnknown *) + sizeof(ULONG));
// Get the next row, and get the pointer to ISequentialStream.
HROW * rghRows = NULL;
ULONG cRows;
pIRowset->GetNextRows(NULL, 0, 1, &cRows, &rghRows);
pIRowset->GetData(rghRows[0], hAccessor, pData);
// Read and process 5000 bytes at a time.
BYTE rgBuffer[5000];
ULONG cb;
if ((ULONG)((BYTE*)pData)[rgBinding[0].obStatus] == DBSTATUS_S_ISNULL) {
// Process NULL data.
} else if ((ULONG)((BYTE *)pData)[rgBinding[0].obStatus] ==
DBSTATUS_S_OK) {
//Obtain pointer to ISequentialStream.
pISequentialStream = *(ISequentialStream **)pData;
do {
pISequentialStream->Read(rgBuffer, // Buffer to write the data
sizeof(rgBuffer), // Number of bytes to get
&cb); // Number of bytes written to buffer
if (cb > 0) // Check to see if we got data
{
// Process data here.
}
} while (cb >= sizeof(rgBuffer));
};
pIMalloc->Free(rghRows);
};
There are two ways a consumer can set BLOB data by using a storage object:
It is permissible to open an ISequentialStream storage object with both read and write access (STGM_READWRITE). With such an object, there is a single "current position" that is incremented by both the ISequentialStream::Read and the ISequentialStream::Write methods. In this case, a write would overlay the contents of the stream.
To write data directly to the provider's storage object, the consumer performs the following actions:
The consumer must specify that it needs to have write access to the storage object by at least requesting STGM_WRITE. For more information, see "Binding BLOB Data as a Storage Object," earlier in this section.
The provider creates a storage object over the BLOB's data and returns a pointer to the requested storage interface (ISequentialStream, IStream, IStorage, or ILockBytes) on this object. Because IRowsetChange::SetData is not called, this technique does not require IRowsetChange, so there is no requirement that DBPROP_IRowsetChange is VARIANT_TRUE. If the provider supports deferred validation of accessors and if the provider cannot deliver an updatable storage object, writing directly to the storage object would fail with a bad binding status (such as DBBINDSTATUS_E_BADSTORAGEFLAG) on either IAccessor::CreateAccessor or IRowset::GetData.
If the provider supports only a single open storage object at a time and another storage object is open, the method returns a status of DBSTATUS_E_CANTCREATE for the column.
Character data set with these methods is not null-terminated.
For a similar code example, see "Getting BLOB Data with Storage Objects," earlier in this section. The code for setting BLOB data is essentially the same, except that the consumer must set the dwFlags element of the ObjectStruct structure so that it can write to the storage object. Also, the consumer calls ISequentialStream::Write instead of ISequentialStream::Read.
To pass a pointer to its own storage object, the consumer must perform the following actions:
If the consumer's storage object exposes ISequentialStream and the provider needs to know the number of bytes of BLOB data that will be sent before any of the data is sent, this accessor must also bind the length of the BLOB column. For more information, see "Limitations of Storage Objects," earlier in this chapter.
If the provider already has a storage object open over the BLOB's data, the method might return a status of DBSTATUS_E_CANTCREATE for the column. The provider reads the data from the consumer's stream in order to update the column. The provider may read the data at the time IRowsetChange::SetData or IRowsetChange::InsertRow is called, or (if the rowset is in deferred update mode) may defer reading the data until IRowsetUpdate::Update or IRowsetUpdate::Undo is called for the row, or until IRowsetChange::SetData is called again for the same column in the same row. Thus, the consumer's storage object must be valid upon IRowsetChange::SetData or IRowsetChange::InsertRow and must remain valid until the provider releases it. When the provider has finished using the consumer's storage object, it calls IUnknown::Release to release the pointer. For more information about releasing the reference to a storage object, see "Releasing a reference to a storage object" in this section.
If the provider needs to know the number of bytes of BLOB data that will be sent before any of the data is sent, it uses the Stat method on the consumer's storage object if the consumer's storage object exposes IStream, IStorage, or ILockBytes, or retrieves this number from the length part of the binding if the consumer's storage object exposes ISequentialStream. If the consumer binds the length and the provider does not need to know this information, or if the consumer's storage object exposes IStream, IStorage, or ILockBytes, the provider ignores the bound length value.
To set the BLOB column to a zero-length value, the consumer sets the status flag to DBSTATUS_S_OK. It then either passes a null pointer (instead of a pointer to its own storage object) or passes a pointer to a storage object that contains no data. The provider sets the column to a zero-length value. This is different from setting the status value for the column to DBSTATUS_S_ISNULL. If the consumer sets the column value to NULL and then calls IRowset::GetData, the GetData method returns a status value of DBSTATUS_S_ISNULL. If the consumer sets the column to a zero-length value and then calls IRowset::GetData, the GetData method returns a pointer to a storage object that contains no data.
Note Not all providers support setting a BLOB column to a zero-length value.
Releasing a reference to a storage object
The provider must release any references on the storage object by the time the row is successfully updated or the change is undone or overwritten; if the rowset is in immediate update mode, the provider must not hold any pointers or reference counts on the consumer's storage object after the call to IRowsetChange::SetData or IRowsetChange::InsertRow in which the storage object is passed. If the rowset is in deferred update mode, the provider must not hold any pointers or reference counts on the consumer's storage object after IRowsetUpdate::Update or IRowsetUpdate::Undo has been called successfully for the row or after IRowsetChange::SetData has been successfully called to replace the contents of the column. If the consumer wants to ensure access to its storage object after SetData returns, it must call IUnknown::AddRef on the pointer before calling IRowsetChange::SetData.
In general, the provider is responsible for releasing storage objects, on either rowsets (IRowsetChange::SetData, IRowsetChange::InsertRow) or rows (IRowChange::SetColumns, IRowSchemaChange::AddColumns), both on success and on any errors. The provider is responsible for releasing storage objects of column types DBTYPE_IUNKNOWN and DBTYPE_IUNKNOWN | DBTYPE_BYREF. It is the consumer's responsibility to release storage objects of type DBTYPE_IDISPATCH or to release any storage object embedded in the following types: DBTYPE_VARIANT, DBTYPE_PROPVARIANT, DBTYPE_VECTOR, and DBTYPE_ARRAY. For more information, see the applicable interface and method descriptions in the "OLE DB Reference" section of this documentation.
Code example of passing a pointer to a storage object
The following code passes a pointer to a different ISequentialStream object to IRowsetChange::SetData to overwrite the existing value:
#include<oledb.h>
IRowsetChange * pIRowsetChange;
IAccessor * pIAccessor;
ISequentialStream * pISeqStr;
HROW hrow;
int main() {
// Assume the consumer has a pointer (pIRowsetChange)
// that points to the rowset's IRowsetChange interface
// and a pointer (pISeqStr) that points to an
// ISequentialStream object not in the rowset. Create an
// accessor for the BLOB column. Assume it is column 1.
HACCESSOR hAccessor;
DBBINDSTATUS rgStatus[1];
DBOBJECT &ObjectStruct;
DBBINDING rgBinding[1] = {
1, // Column 1
0, // Offset to data
sizeof(IUnknown*), // obLength length field
0, // Ignore status field
NULL, // No type info
ObjectStruct, // Object structure
NULL, // Ignore binding extension
DBPART_VALUE|DBPART_LENGTH, // Bind value and length
DBMEMOWNER_CLIENTOWNED, // Consumer owned memory
DBPARAMIO_NOTPARAM, // Not a parameter binding
0, // Ignore maxlength
0, // Reserved
DBTYPE_IUNKNOWN, // Type DBTYPE_IUNKNOWN
0, // Precision not applicable
0, // Scale not applicable
};
// Set the elements in the object structure so that the
// provider creates a writable ISequentialStream object
// over the column. The provider will read data from the
// ISequentialStream object passed to SetData and will
// write it to this object.
ObjectStruct.dwFlags = STGM_READ ;
ObjectStruct.iid = IID_ISequentialStream;
pIRowsetChange->QueryInterface(IID_IAccessor, (void**) &pIAccessor);
pIAccessor->CreateAccessor(DBACCESSOR_ROWDATA, 1, rgBinding, sizeof(IUnknown *),
pIAccessor->Release();
// Assume you already have a row handle (HROW). Call
// SetData and pass it the address of the pointer to the
// object ISequentialStream not in the rowset. The rowset
// will copy the data from the ISequentialStream object to
// the rowset. Set up pData row buffer.
BYTE* pData=(BYTE*)CoTaskMemAlloc(sizeof(IUnknown*)+sizeof(ULONG));
// Value - pass ISequentialStream pointer to the provider.
*(ISequentialStream**)(pData+rgBinding[0].obValue)=pISeqStr;
// LENGTH - Some providers need to know the length of the
// stream ahead of time...
*(ULONG*)(pData+rgBinding[0].oblength)=5000;
// SetData - The provider will then do an ISequentialStream::Read
// on the pISeqStr pointer passed in...
pIRowsetChange->SetData(hrow, hAccessor, pData);
CoTaskMemFree(pData);
return 0;
} ;
Consumers get and set BLOBs and COM objects in command parameters in a manner similar to accessing BLOB columns.