BLOB 访问接口:ISPExternalBinaryProvider
上次修改时间: 2015年3月9日
适用范围: SharePoint Foundation 2010
本文内容
接口定义 (IDL)
StoreBinary 方法参数
RetrieveBinary 方法参数
外部二进制大型对象 (BLOB) 存储(EBS 提供程序)作为 COM 组件集成到 Microsoft SharePoint Foundation 2010 的 SharePoint 存储访问堆栈中。EBS 提供程序的核心是 ISPExternalBinaryProvider 接口,您必须实现该接口才能编写自定义提供程序。该接口包含 StoreBinary 和 RetrieveBinary 两个方法,通过实现这两个方法,可在外部 BLOB 存储中存储和检索二进制数据。
接口定义 (IDL)
SharePoint 应用程序包含 ISPExternalBinaryProvider 类的公共的无状态实例。当您要在外部 BLOB 存储区中存储或检索 BLOB 数据时,将调用此持久性实例。
接口 IDL 文件(extstore.idl)的内容如下所示:
/*************************************************
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 方法参数
以下是 StoreBinary 方法的参数的相关说明。
[in] unsigned long cbPartitionId
传递给 pbPartitionId 参数的字节数组的大小。SharePoint Foundation 始终将此值指定为 16,这表示一个 GUID 的大小。
[in, size_is(cbPartitionId)] const byte* pbPartitionId
二进制文件所在的网站的标识符。EBS 提供程序可以使用此标识符将 BlobId 参数映射到外部 BLOB 存储中的逻辑集合。
[in] ILockBytes* pilb
指向作为 ILockBytes 实例的 BLOB 数据的指针。Important:在返回 HRESULT 后提供程序不得保存对 ILockBytes* 对象的引用。
[out] unsigned long* pcbBinaryId
BLOB ID 中的字节数。
[out, size_is(, *pcbBinaryId)] byte** ppbBinaryId
在将 BLOB 存储到外部 BLOB 存储中之后,从 EBS 提供程序输出参数。EBS 提供程序可为外部 BLOB 存储提供此 ID,或者,此外部 BLOB 存储可以返回 EBS 提供程序。SharePoint Foundation 不指定要使用的方法。但建议您选择一种适用于将来版本的 EBS 提供程序的方法。
此参数应通过使用 CoTaskMemAlloc 来分配。
[out,optional] VARIANT_BOOL* pfAccepted
一个布尔参数。FALSE 指示 SharePoint Foundation 应以嵌入方式存储 BLOB 文件。在某些情况下,当 SharePoint Foundation 无法支持拒绝 BLOB 的 EBS 提供程序时(即,当为链接修复或病毒扫描更新文件时),SharePoint Foundation 将传递 NULL 指针。如果发生这种情况,则 EBS 提供程序必须存储该文件或返回失败 HRESULT。
RetrieveBinary 方法参数
以下是对 RetrieveBinary 方法的参数的说明。请注意,这些参数本身与 StoreBinary 方法的参数相同。
[in] unsigned long cbPartitionId
传递给 pbPartitionId 的字节数组的大小。SharePoint Foundation 始终将此值指定为 16,这表示一个 GUID 的大小。[in, size_is(cbPartitionId)] const byte* pbPartitionId
二进制文件所在的网站的标识符。EBS 提供程序可以使用此标识符来将 BLOB ID 映射到外部 BLOB 存储中的逻辑集合。[in] unsigned long cbBinaryId
BLOB ID 中的字节数。[in, size_is(cbBinaryId)] const byte* pbBinaryId
传递给 EBS 提供程序的标识符,用于查找外部 BLOB 存储中的 BLOB。[out] ILockBytes** ppilb
指向作为 ILockBytes 实例的 BLOB 数据的指针。
StoreBinary 的返回值
以下是在使用 ISPExternalBinaryProvider:StoreBinary 方法时的返回值及其说明。
S_OK |
方法成功运行。 如果 SharePoint Foundation 为 *pfAccepted 传递非 NULL 地址,则当 *pfAccepted 为 VARIANT_FALSE 时,此文件将存储在 SQL Server 中。否则,SharePoint Foundation 会将该值存储在 ppbBinaryId 中的值并记录已在外部存储 BLOB。 |
E_FAIL |
SharePoint Foundation 告知用户文件尚未存储;此外,SharePoint Foundation 不会更改任何输出参数。(如果已调用 CoTaskMemAlloc,则假定 EBS 提供程序已调用 CoTaskMemFree。) |
SharePoint Foundation 将记录意外的 HRESULT 返回结果,并对成功或失败的 HRESULT 做出相应的响应。
RetrieveBinary 的返回值
以下是在使用 ISPExternalBinaryProvider:RetrieveBinary 方法时的返回值及其说明。
S_OK |
方法成功运行。 SharePoint Foundation 从 *ppilb 参数读取文件内容,然后将其发布。 |
E_FAIL |
方法执行失败。 SharePoint Foundation 告知用户无法检索该文件。SharePoint Foundation 不会更改 *ppilb 参数中的值。 |
提供程序将 ILockBytes 接口返回到存储访问堆栈。
和 StoreBinary 方法一样,EBS 提供程序负责记录检索事件。Windows SharePoint Services 会记录意外的 HRESULT 返回结果,但将执行其他操作,就好像返回结果只不过是 S_OK 或 E_FAIL。