BLOB Access Interface: ISPExternalBinaryProvider

Applies to: SharePoint Foundation 2010

The external binary large object (BLOB) store—the EBS Provider—is integrated into the SharePoint storage access stack of Microsoft SharePoint Foundation 2010 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. SharePoint Foundation 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. SharePoint Foundation 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 SharePoint Foundation that the BLOB file should be stored inline. Under some circumstances, as when SharePoint Foundation cannot support the EBS Provider rejecting a BLOB (that is, when a file is updated for link fix-up or virus scan), SharePoint Foundation 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. SharePoint Foundation 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.

S_OK	The method ran successfully. If SharePoint Foundation passed *pfAccepted with a non-NULL address, the file is stored in SQL Server in cases where *pfAccepted is VARIANT_FALSE. Otherwise SharePoint Foundation stores the value in ppbBinaryId and records that the BLOB was stored externally.
E_FAIL	SharePoint Foundation indicates to the user that the file was not stored; further, SharePoint Foundation does not alter any of the out parameters. (The EBS Provider is assumed to have called CoTaskMemFree if CoTaskMemAlloc was called.)

SharePoint Foundation 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.

S_OK	The method ran successfully. SharePoint Foundation reads the file content from the *ppilb parameter and then releases it.
E_FAIL	Execution of the method failed. SharePoint Foundation indicates to the user that the file could not be retrieved. SharePoint Foundation does not alter the value in the *ppilb parameter.

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 Storage of Binary Large Objects (BLOBs) in SharePoint Foundation