IdmaContentTransfer

This interface provides access to content data (represented by objects of dmaClass_ContentTransfer) which is directly captured and managed by a document space.

IdmaContentTransfer::CopyToResource

Support for this method is optional.

Syntax
DmaRC IdmaContentTransfer::CopyToResource (
pDmaString pDestName,
DmaInteger32 flags)

Parameters

Makes a copy of the captured data in a resource of the specified name.

This method is optional on already persistent content transfer elements and should return DMARC_NOT_SUPPORTED on a content transfer element which has not yet been saved.

If the copy occurs successfully the client is responsible for removing the resource when it is no longer needed. The resource is owned by the client, and the content transfer element will retain no memory of its existence.

The flags parameter is a bitwise OR of any of the following integer values:

DMA_CREATE_REPLACE_EXISTING

This flag dictates behaviour if the resource named by pDestName already exists
at the time this method is called. If the flag is set, the resource should be replaced 
with the source material. 
If this flag is not set, the method leaves the existing resource intact and returns
DMARC_NO_ACCESS. This flag is ignored if the specified resource
does not yet exist.

DMA_CREATE_PRESERVE_DATETIME
Specifies how the creation time of the resource should be set. If the flag is set 
and the document space has recorded the creation time of incoming 
document content, the creation time of the new resource is set to original 
creation time of the document content. If the flag is not set, the creation 
time for the resource should be set according to platform defaults. 
(Typically, to the current time).

For a document space which supports content replacement, a call to SetCaptureStream or SetCaptureResource causes subsequent calls to this method to behave as for the new case, which is to return DMARC_NOT_SUPPORTED. In other words, the existing content rendered inaccessible through this content element instance.

It is not required that a document space which supports this method support all possible forms of URL. However, at minimum the file: form should be supported.

If the URL supplied includes security credentials, these should be used to access the resource in order to complete the data transfer. Otherwise, the operation must be performed using the security context of the calling thread. This should hold irrespective of whether the service provider operates in a separate process with its own security context.

Return Values

IdmaContentTransfer::GetResourceName

Support for this method is optional.

Syntax
DmaRC IdmaContentTransfer::GetResourceName (
ppDmaString ppName)

Parameters

This method behaves differently according to whether it is applied to a new (unsaved) content element or to an existing persistent content element.

In the former case, this method provides a way to interrogate the capture mode for the object. If resource name mode has been specified, the method will return a copy of the URL supplied to SetCaptureResource. If stream mode has been specified or no mode has yet been set, the method will return DMARC_VALUE_NOT_SET.

In the latter case this method returns a resource name that the client application may be able use to directly access the captured content data.

This methods makes no guarantee that the application will in fact be able to access the content data via the resource name returned, since this depends on the protocol specified in the URL and on the security which is applied to it.

For a docspace which supports content replacement, a call to SetCaptureStream or SetCaptureResource causes subsequent calls to this method to behave as for the new case. In other words, the existing content is rendered inaccessible through this content element instance.

This method must be supported if SetCaptureResource is supported; otherwise support is optional.

Return Values

IdmaContentTransfer::GetStream

This method must be supported in every implementation of this interface.

Syntax
DmaRC IdmaContentTransfer::GetStream (
DMA_REFIID riid,
pDmapv ppIStream)

Parameters

This method behaves differently according to whether it is applied to a new (unsaved) content element or to an existing persistent content element.

In the former case, this method provides a way to interrogate the capture mode for the object. If stream mode has been specified, the method will return a reference to the stream object supplied to SetCaptureStream. If resource name mode has been specified or no mode has yet been set, the method will return DMARC_VALUE_NOT_SET.

In the latter case, the method returns a stream object providing direct access to the captured content data.

In both cases, the method exhibits "by reference" behaviour. A second or subsequent call returns a reference to the same object as the first call. In both cases, the position of the seek pointer on the stream object is undefined.

For a document space which supports content replacement, a call to SetCaptureStream or SetCaptureResource causes subsequent calls to this method to behave as for the new case. In other words, the existing content is rendered inaccessible through this content element instance.

Return Values

IdmaContentTransfer::SetCaptureResource

Support for this method is optional.

Syntax
DmaRC IdmaContentTransfer::SetCaptureResource (
pDmaString pResourceName)

Parameters

Requests content capture from a named resource (aka "by filename").

This method is optional. Where supported, it may be so only for new (unsaved) content transfer element objects or for already saved content transfer elements (allowing for content replacement).

It is strongly recommended that the document space validate the resource name at the time of this method invocation, to determine that it is of a supported syntax and refers to an existing resource. It is not however recommended that the document space attempt to place a lock of some kind on the resource in an attempt to ensure its availability through to the time the content element is saved, since this may be expensive and may interfere with other legitimate operations which take place in the interim. It is therefore the case that (re)validation must be performed at the time the content element is made persistent.

It is not required that a document space which supports this method support all possible forms of URL. However, at minimum the file: form should be supported.

If the client application does not set a value for the Retrieval Name property of the content transfer element object to which this method is applied, the implementation is permitted to parse a suitable value out of pResourceName. However, this should not become visible as the property value until after the content element is made persistent.

If the URL specified includes security credentials, these should be used to access the content data. Otherwise, access to the content data must be attempted under the security context of the client thread which called this method effective at the time of the call, and the ExecuteChange operation should fail if this is not sufficient. This should hold irrespective of whether the service provider operates in a separate process with its own security context.

Return Values

Deferred Return Values

IdmaContentTransfer::SetCaptureStream

This method must be supported in every implementation of this interface.

Syntax
DmaRC IdmaContentTransfer::SetCaptureStream (
Dmapv pStream)

Parameters

Requests content capture from a stream and specifies the stream from which to capture. This method must be supported on a new (not yet saved) content transfer element by all document space implementations. A document space which supports update of captured content may also allow this on a previously saved content transfer element as a way of effecting content replacement.

This method may be invoked an arbitrary number of times, in arbitrary combination with calls to SetCaptureResource on the same content transfer object. The ultimate effect when this object is saved is as if only the most recent call had been issued.

The stream supplied must be positioned at the beginning of the data to be captured. The implementation must capture the data using only the ReadStreamData method of the stream, since the stream is not required to support arbitrary positioning.

Return Values

Deferred Return Values