This is the specialized interface for the DMA Document Space object. It provides methods for construction of new objects in the Document Space and for manipulating objects that are managed by the Document Space.
Support for this method is optional.
Syntax
DmaRC IdmaDocSpace::ConnectAndLockObject (
pDmaString pObjectId,
DmaInteger32 lLockType,
DMA_REFIID riid,
pDmapv ppIObject)
Parameters
Name | Mode | Description |
pObjectId | input | A pointer to the globally unique object instance identifier (OIID) of the persistent object to be retrieved. |
lLockType | input | The type of lock to be obtained on the object. One of DMA_LOCK_READ, DMA_LOCK_WRITE, or DMA_LOCK_EXIST. |
riid | input | Interface Identifier for the desired interface on the resulting object. |
ppIObject | output | An interface on the object created, which will be NULL if the method fails. |
ConnectAndLockObject is the same as ConnectObject, except that a lock is atomically placed on the object connected to if the method succeeds. This method is supported if and only if the locking methods (i.e., ApplyLock and RemoveLock) are supported.
Return Values
Name | Description |
DMARC_ACCESS_DENIED | (E_ACCESSDENIED) The requester has insufficient access rights to perform the requested operation. |
DMARC_BAD_INTERFACE | (E_NOINTERFACE) The requested interface is not supported by this object. |
DMARC_BAD_LOCK_TYPE | The lock type is invalid. |
DMARC_BAD_OIID | The supplied buffer does not contain a valid OIID. |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_LOST_CONNECTION | The logical connection of the current object to the persistent store has been lost permanently. The operation could not be completed. |
DMARC_NO_MEMORY | (E_OUTOFMEMORY) Insufficient memory to complete the operation. |
DMARC_NOT_AUTHENTICATED | The user is not authenticated. |
DMARC_NOT_FOUND | Requested item not found. |
DMARC_NOT_SUPPORTED | This method is not supported in the context of this session or object. |
DMARC_OBJECT_LOCKED | The lock(s) on the persistent object prohibit the attempted operation. |
DMARC_OK | (S_OK) Success. |
Support for this method is optional.
Syntax
DmaRC IdmaDocSpace::ConnectObject (
pDmaString pObjectId,
DMA_REFIID riid,
pDmapv ppIObject)
Parameters
Name | Mode | Description |
pObjectId | input | A pointer to the globally unique object instance identifier (OIID) of the persistent object to be retrieved. This identifier may be known by the caller or obtained from previously instantiated objects. |
riid | input | Interface Identifier for the desired interface on resulting object. |
ppIObject | output | An interface on the object created, which will be NULL if unsuccessful on an initial open. |
ConnectObject makes a scratchpad copy in the client's process space of the referenced persistent object (I.e. it instantiates an object that is already persistent). A snapshot of the object’s properties will be set from the persistent store; they may be changed using the IdmaEditProperties interface. Changes can be made persistent using the IdmaConnection::ExecuteChange method.
At any time the object can be checked against the persistent copy for consistency using the IdmaConnection::IsCurrent call. If the object has changed, or the caller simply wants the properties refreshed, the IdmaConnection::ExecuteRefresh call may be used. That method will not instantiate a new object, but will retrieve a new copy of the persistent information into the existing instance.
If the persistent object has been locked for exclusive use by another connection, the ConnectObject method will not be successful.
If the returned object does not support the interface specified by riid, the operation will fail and the result code DMARC_BAD_INTERFACE will be returned. In case the operation is successful, the returned interface must be released using the method IUnknown::Release.
If pObjectId does not refer to an existing persistent object, DMARC_NOT_FOUND will be returned.
This method fails with the error DMARC_NOT_AUTHENTICATED if the document space is not in an authenticated state.
Return Values
Name | Description |
DMARC_BAD_INTERFACE | (E_NOINTERFACE) The requested interface is not supported by this object. |
DMARC_BAD_OIID | The supplied buffer does not contain a valid OIID. |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_NOT_AUTHENTICATED | The user is not authenticated. |
DMARC_NOT_FOUND | Requested item not found. |
DMARC_NOT_SUPPORTED | This method is not supported in the context of this session or object. |
DMARC_OBJECT_LOCKED | The lock(s) on the persistent object prohibit the attempted operation. |
DMARC_OK | (S_OK) Success. |
DMARC_STALE_METADATA | The metadata in the persistent store has been changed so that it does not match the client's current copy of the metadata. |
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaDocSpace::ExecuteDisconnect ( )
Terminates the logical connection to the underlying document repository. This may be useful to free up connection resources in environments in which direct control cannot be exercised over the lifetime of the DocSpace COM object and objects obtained from it.
Once this method is executed successfully, other methods (on the DocSspace object or objects obtained from it) that need the connection to function will return DMARC_DISCONNECTED.
Note that if the DocSpace object and all objects generated from it are released, the connection is implicitly closed. ExecuteDisconnect() just provides a way of doing this explicitly. Once a DocSpace object is disconnected, it cannot be reconnected.
Return Values
Name | Description |
DMARC_NOT_AUTHENTICATED | The user is not authenticated. |
DMARC_OK | (S_OK) Success. |
Support for this method is optional.
Syntax
DmaRC IdmaDocSpace::GetScope (
DMA_REFIID riid,
pDmapv ppIScope)
Parameters
Name | Mode | Description |
riid | input | Interface Identifier for the desired interface on resulting Document Space object. |
ppIScope | output | Returns the selected interface for the merged scope object. |
Returns a Scope Object for the Document Space. The scope supplies the meta-data used to formulate the parameters for a query operation and to execute a query operation.
Cross document space queries can be performed by placing document space scope objects on an object list and using the IdmaScopeFactory::CreateScope function to create a merged scope. The merged scope can be used to formulate and execute queries coordinated across multiple document spaces.
If the returned object does not support the interface specified by riid, the operation will fail and the result code DMARC_BAD_INTERFACE will be returned. In case the operation is successful, the returned interface must be released using the method IUnknown::Release.
This method fails with the error DMARC_NOT_AUTHENTICATED if the document space is not in an authenticated state.
Return Values
Name | Description |
DMARC_BAD_INTERFACE | (E_NOINTERFACE) The requested interface is not supported by this object. |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_NOT_AUTHENTICATED | The user is not authenticated. |
DMARC_NOT_SUPPORTED | This method is not supported in the context of this session or object. |
DMARC_OK | (S_OK) Success. |