The BLOB Access Interface: ISPExternalBinaryProvider

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The external binary large object (BLOB) store—the EBS Provider—is integrated into the SharePoint storage access stack of Windows SharePoint Services as a COM component. The core of the EBS Provider is an interface, ISPExternalBinaryProvider, which you must implement to write your custom provider. The interface has two methods, StoreBinary and RetrieveBinary, which you implement to store and retrieve binary data to and from the external BLOB store.

Interface Definition (IDL)

Your SharePoint application holds a common, stateless instance of the ISPExternalBinaryProvider class. This persistent instance gets called when you want to store or retrieve BLOB data from the external BLOB store.

The contents of the interface IDL file (extstore.idl) are as follows:

/*************************************************
    File: extstore.idl
    Copyright (c): 2006 Microsoft Corp.
*************************************************/
import "objidl.idl";

[
    uuid(39082a0c-af6e-4ac2-b6f0-1a1ff6abbae1)
]

library SharePointBinaryStore
{
    [
        local,
        object,
        uuid(48036587-c8bc-4aa0-8694-5a7000b4ba4f),
        helpstring("ISPExternalBinaryProvider interface")
    ]
    interface ISPExternalBinaryProvider : IUnknown
    {
        HRESULT StoreBinary(
            [in] unsigned long cbPartitionId,
            [in, size_is(cbPartitionId)] const byte* pbPartitionId,
            [in] ILockBytes* pilb,
            [out] unsigned long* pcbBinaryId,
            [out, size_is(, *pcbBinaryId)] byte** ppbBinaryId,
            [out,optional] VARIANT_BOOL* pfAccepted);

        HRESULT RetrieveBinary(
            [in] unsigned long cbPartitionId,
            [in, size_is(cbPartitionId)] const byte* pbPartitionId,
            [in] unsigned long cbBinaryId,
            [in, size_is(cbBinaryId)] const byte* pbBinaryId,
            [out] ILockBytes** ppilb);
    }
}

StoreBinary Method Parameters

Following are descriptions for the parameters of the StoreBinary method.

[in] unsigned long cbPartitionId

Size of the byte array passed to the pbPartitionId parameter. Windows SharePoint Services always specifies this value to be 16, which is the size of a GUID.

[in, size_is(cbPartitionId)] const byte* pbPartitionId

Identifier of the site where the binary file belongs. The EBS Provider can use this to map the BlobId parameter to logical collections in the external BLOB store.

[in] ILockBytes* pilb

Pointer to the BLOB data as an ILockBytes instance. Important: The provider must not hold a reference to the ILockBytes* object after returning the HRESULT.

[out] unsigned long* pcbBinaryId

The number of bytes in the BLOB ID.

[out, size_is(, *pcbBinaryId)] byte** ppbBinaryId

Out parameter from the EBS Provider after the BLOB is stored in the external BLOB store. The EBS Provider can provide this ID to the external BLOB store, or the store can return an EBS Provider. Windows SharePoint Services does not specify which approach to use. However, it is recommended that you select an approach that can be adapted to future versions of the EBS Provider.

This parameter should be allocated by using CoTaskMemAlloc.

[out,optional] VARIANT_BOOL* pfAccepted

A Boolean parameter. FALSE indicates to Windows SharePoint Services that the BLOB file should be stored inline. Under some circumstances, as when Windows SharePoint Services cannot support the EBS Provider rejecting a BLOB (that is, when a file is updated for link fix-up or virus scan), Windows SharePoint Services passes a NULL pointer. When this occurs, the EBS Provider must either store the file or return a failure HRESULT.

RetrieveBinary Method Parameters

Following are descriptions for the parameters of the RetrieveBinary method. Note that the parameters themselves are the same as for the StoreBinary method.

• [in] unsigned long cbPartitionId
  Size of the byte array passed to pbPartitionId. Windows SharePoint Services always specifies this value to be 16, which is the size of a GUID.

• [in, size_is(cbPartitionId)] const byte* pbPartitionId
  Identifier of the site where the binary file belongs. The EBS Provider can use this to map the BLOB ID to logical collections within the external BLOB store.

• [in] unsigned long cbBinaryId
  The number of bytes in the BLOB ID.

• [in, size_is(cbBinaryId)] const byte* pbBinaryId
  Identifier passed to the EBS Provider to locate the BLOB in the external BLOB store.

• [out] ILockBytes** ppilb
  Pointer to the BLOB data as an ILockBytes instance.

Return Values for StoreBinary

Following are return values and their descriptions when using the ISPExternalBinaryProvider:StoreBinary method.

Windows SharePoint Services logs unexpected HRESULT returns and reacts appropriately to both successful and failed HRESULTs.

Return Values for RetrieveBinary

Following are return values and their descriptions when using the ISPExternalBinaryProvider:RetrieveBinary method.

The Provider returns an ILockBytes interface to the storage access stack.

As with the StoreBinary method, the EBS Provider is responsible for logging retrieval events. Windows SharePoint Services logs unexpected HRESULT returns, but otherwise acts as though returns are simply S_OK or E_FAIL.

See Also

Concepts

External Storing of Binary Large Objects (BLOBs) in Windows SharePoint Services