IDSSObjectContext Interface Reference

Inherited by IDSSObjectContext2.

List of all members.

---

Detailed Description

Main interface on object context component.

An object context object acts as a source of objects from a session. The context component isolates its user against other changes made in the same session. It ensures that the objects returned from the context do not suffer from broken weak references.

We expect users to create a fresh object context for each operation that involves examining or manipulating multiple DSS Objects. The context will manage the objects that have been used by the operation. When the operation is completed the object context should be deleted.

In general an object context is not thread safe. It is safe to share a read-only object context across threads that do not call methods that return the CONTEXT_E_READ_ONLY error. In particular a read-only context could safely be the child context of several different read-write contexts that are used by different threads.

See also:

IDSSObjectContextFactory

Public Member Functions
HRESULT	AddChild ([in] IDSSObjectContext *pChild,[in, defaultvalue(0)] VARIANT_BOOL IsMerged)
	Add an existing object context to the collection of child contexts of this context.
HRESULT	ChildCount ([out, retval] Int32 *pCount)
	Get the number of immediate child contexts of this context.
HRESULT	ChildItem ([in] Int32 Index,[out, retval] IDSSObjectContext ppChild)
	Get a child context specified by its index number.
HRESULT	ClearChildren ()
	Remove all child contexts from this context.
HRESULT	CopyContext ([in, defaultvalue(0)] EnumDSSContextFlags Flags,[out, defaultvalue(0)] IDSSObjectContext oppNewHeadEditContext,[out, defaultvalue(0), retval] IDSSObjectContext oppNewContext)
	Duplicate this object context component.
HRESULT	CopyObject ([in] IDSSObjectInfo *pKey,[in, defaultvalue(0)] IDSSObjectInfo *pProject,[in, defaultvalue(0)] EnumDSSContextFlags Flags,[out, retval] IDSSObjectInfo2 ppObject)
	Create a new object within this context by copying an existing object.
HRESULT	Count ([out, retval] Int32 *pCount)
	Get the number of objects about which the context directly records information.
HRESULT	EditContext ([in, defaultvalue(0)] VARIANT_BOOL EnsureContext,[out, retval] IDSSObjectContext ppEditContext)
	Get the edit context for this context.
HRESULT	ExecuteSearch ([in] IDSSSearch *pSearchObject,[in, defaultvalue(0)] Int32 pFlags,[in, defaultvalue(0)] IDSSFolder *pExistingFolder,[out, retval] IDSSFolder ppNewFolder)
	Search objects through the context and metadata together.
HRESULT	FindEmbeddedObjectByID ([in] BSTR ID,[in] EnumDSSObjectType Type,[in, defaultvalue("")] BSTR ContainerID,[in, defaultvalue(0)] EnumDSSObjectType ContainerType,[in, defaultvalue("")] BSTR ProjectID,[in, defaultvalue(1)] EnumDSSContextStatus Status,[in, defaultvalue(0)] EnumDSSContextFlags Flags,[out, retval] IDSSObjectInfo2 ppObject)
	Get an instance of an embedded object specified by ID.
HRESULT	FindObject ([in] IDSSObjectInfo *pKey,[in, defaultvalue(1)] EnumDSSContextStatus Status,[in, defaultvalue(0)] EnumDSSContextFlags Flags,[out, retval] IDSSObjectInfo2 ppObject)
	Get an instance of the specified object.
HRESULT	FindObjectByID ([in] BSTR ID,[in] EnumDSSObjectType Type,[in, defaultvalue("")] BSTR ProjectID,[in, defaultvalue(1)] EnumDSSContextStatus Status,[in, defaultvalue(0)] EnumDSSContextFlags Flags,[out, retval] IDSSObjectInfo2 ppObject)
	Get an instance of an object specified by ID.
HRESULT	GetContextInfo ([in] IDSSObjectInfo *pKey,[out, retval] IDSSObjectContextInfo ppContextInfo)
	Get information about a particular object in the context.
HRESULT	IsChildMerged ([in] IDSSObjectContext *pChild,[out, retval] VARIANT_BOOL *pIsMerged)
	Get whether the given context is merged with this context..
HRESULT	IsMerged ([out, retval] VARIANT_BOOL *pIsMerged)
	Get whether this context has been merged with some other context.
HRESULT	IsReadOnly ([in] VARIANT_BOOL ReadOnly)
	Put whether this context is read-only.
HRESULT	IsReadOnly ([out, retval] VARIANT_BOOL *pReadOnly)
	Get whether this context is read-only.
HRESULT	NewContextCollection ([out, retval] IDSSContextCollection oppCollection)
	Construct a new context collection based on this context.
HRESULT	NewIterator ([in, defaultvalue(0)] EnumDSSContextFlags Flags,[out, retval] IDSSObjectContextIterator ppIterator)
	Get an iterator to walk through the members in the object context.
HRESULT	NewObject ([in] EnumDSSObjectType Type,[in, defaultvalue(0)] IDSSObjectInfo *pProject,[in, defaultvalue(0)] EnumDSSContextFlags Flags,[out, retval] IDSSObjectInfo2 ppObject)
	Create a new object within this context with the specified object type.
HRESULT	Remove ([in] IDSSObjectInfo *pObject,[in, defaultvalue(0)] EnumDSSContextFlags Flags)
	Remove a given object from the object context.
HRESULT	RemoveChild ([in] IDSSObjectContext *pChild)
	This context should no longer consider the given context as a child context.
HRESULT	SaveAll ([in, defaultvalue(0)] EnumDSSContextFlags Flags)
	Save all changes from this context to the object source.
HRESULT	Source ([out, retval] IDSSSource4 ppSource)
	Get the object source that backs up this context.
HRESULT	TakeOwnership ([in] IDSSObjectInfo *pObject,[in, defaultvalue(0)] EnumDSSContextFlags Flags)
	Move an owned object to a given merged context.
HRESULT	UserRuntime ([out, retval] IDSSUserRuntime ppRuntime)
	Get the user runtime for the user who made this context.

---

Member Function Documentation

HRESULT IDSSObjectContext::AddChild (  [in] IDSSObjectContext *  pChild, [in, defaultvalue(0)] VARIANT_BOOL  IsMerged )

Add an existing object context to the collection of child contexts of this context. This method has no effect if the context is already a child context of this context. We have two kinds of children: Merged children. Merged contexts share access to each other. The parent can see objects in the child, and the child can see objects in the parent. A context may only have one merged parent, but can have multiple merged children. Merged contexts must all be accessed from the same thread. Read-only children. Parent contexts can see objects from read-only children, but the children cannot see objects from the parents. A read-only child can have multiple parents. The read-only child can be accessed from several threads at the same time. Parameters: pChild  The proposed new child context for this context. IsMerged  Whether the new child should be merged with this context. Returns: Usual COM result code: S_OK Operation was successful. The caller may infer that pChild is a child context of this context. E_INVALIDARG pChild was NULL on entry or IsMerged is not a Boolean value. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only. CONTEXT_E_CHILD_READ_WRITE A non-merged child context must be read-only. CONTEXT_E_CHILD_READ_ONLY A merged child context must be read-write. CONTEXT_E_CYCLIC_DEPENDENCY Cannot perform the operation because this context is already a descendent of pChild. This error is also returned if making the addition would cause the child to have two different merged parents. CONTEXT_E_DIFFERENT_RUNTIME Cannot merge a child context into a parent context if the contexts are using different runtimes. CONTEXT_E_AMBIGUOUS_MEMBER Cannot perform this operation because the pChild owns a different version of some object that is already accessible from another child of this context. CONTEXT_E_OVERRIDDEN_MEMBER Cannot perform this operation because the same object cannot be owned by both parent and child contexts. CONTEXT_E_OVERRIDDEN_DEPENDENT Cannot perform this operation because the child contains an object which has a dependent that is fixed in the parent. CONTEXT_E_EDIT_CONTEXT We cannot merge contexts if either context has an edit context. CONTEXT_E_SOLE_MERGED_CHILD A context can have merged children or read-only children but not both. This error indicates an attempt to add children of both types to the same parent context.

HRESULT IDSSObjectContext::ChildCount (  [out, retval] Int32 *  pCount  )

Get the number of immediate child contexts of this context. This count does not include grandchild contexts or any remoter descendents. It does not matter if a child context has been merged with this context. Parameters: pCount  Return the number of child contexts directly held by the context. Returns: Usual COM result code: S_OK Operation was successful. E_POINTER pCount was NULL on entry.

HRESULT IDSSObjectContext::ChildItem (  [in] Int32  Index, [out, retval] IDSSObjectContext   ppChild )

Get a child context specified by its index number. Parameters: Index  Index number of the requested child context. ppChild  Return the requested child context. Returns: Usual COM result code: S_OK Operation was successful. The caller may assume that *ppChild is non-NULL. E_POINTER ppChild was NULL on entry. DSSCOM_E_INDEX_OUT_OF_RANGE Index was not in the range 1 to ChildCount.

HRESULT IDSSObjectContext::ClearChildren (   )

Remove all child contexts from this context. This method removes both read-only and merged child contexts. Returns: Usual COM result code: S_OK Operation was successful. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only. CONTEXT_E_EDIT_CONTEXT Cannot remove merged child contexts while there is an edit context. The context could contain objects from several merged contexts.

HRESULT IDSSObjectContext::CopyContext (  [in, defaultvalue(0)] EnumDSSContextFlags  Flags, [out, defaultvalue(0)] IDSSObjectContext   oppNewHeadEditContext, [out, defaultvalue(0), retval] IDSSObjectContext   oppNewContext )

Duplicate this object context component. The new object context component contains identical copies of all of the objects in the original object context. If we ever support sharing (to allow two unmodified objects in different contexts to share their data) then owned but not checked out objects would be shared between the original and new context. The caller can choose what happens to the edit context. If no flag is provided any edit context is ignored. The DssContextFlagCopyEditContext flag causes (top-level) objects in the edit context to be copied out as well. The DssContextFlagCopyReuseEdit flag will actually move the edit objects into the copy (so they will be discarded from the original). The DssContextFlagCopyFoldInEditContext flag causes edit context objects to be saved into the copy of the base context. This is an optimization since it removes necessity to copy out objects from the base context that are going to be discarded when the edit context objects are saved. When this method is called on an edit context then one or other of the edit context copy flags must be supplied, and the DssContextFlagCopyFoldInEditContext flag cannot be used. These flags ensure that the copy has an edit context. In this case the method returns the copy of the edit context on which it was called. If there are sereral merged contexts then they are all copied. The contexts will be copied as a tree, maintaining their original relationships. The context returned will always be the root of the merged context tree, regardless of which context this method was called on. Provided calls ask to copy the topmost merged context this will not cause any confusion. Parameters: Flags  Modifiers for this operation. DssContextFlagCopyEditContext Copy includes the edit context as well. DssContextFlagCopyReuseEdit Any edit context objects are moved to the copy. The original's edit contexts will become empty. DssContextFlagCopyFoldInEditContext Any edit context objects are folded into the base context, instead of being held separately. Note this flag has no effect unless one of the previous two flags is also used. oppNewHeadEditContext  Return the topmost edit context used by the copy. Since edit contexts are cleared when the user drops them it is not possible to create new edit contexts unless the user takes a reference on them. oppNewContext  Return the new object context. It is completely disconnected from the original context, but uses the same source, child contexts etc. Returns: Usual COM result code S_OK Success. Caller may assume oppContext is non-NULL. E_POINTER oppContext was NULL on entry. E_INVALIDARG Method was called on edit context, but flags provided did not ask to copy/reuse the edit context. Alternatively flags asked to create new edit context(s), but oppNewHeadEditContext was NULL on entry.

HRESULT IDSSObjectContext::CopyObject (  [in] IDSSObjectInfo *  pKey, [in, defaultvalue(0)] IDSSObjectInfo *  pProject, [in, defaultvalue(0)] EnumDSSContextFlags  Flags, [out, retval] IDSSObjectInfo2   ppObject )

Create a new object within this context by copying an existing object. A newly created object always has checked out status. This method has the same effect as first finding the key object (using the DssContextUnspecified status). Second a new object is created in the context (with the same type as the key object). Third the new object is populated with the content of the object that was found in the first stage. Note that this semantics mean that it is possible for the copy to be made from a different instance of the object from the instance passed in to the method. To save the newly created object as a stand-alone object the user must set the IDSSObjectInfo2::DestinationFolder property of the new object. Otherwise the object will be saved as a managed object. This method cannot be used to create new embedded objects. Instead new embedded objects can be created within a context be checking out the desired container and then calling IDSSEmbeddedFolder::AddCopy on the embedded folder of the container. Parameters: pKey  Instance of the object that should be copied. The object passed into this method does not need to come from this context, or even from same source. The object may be an embedded object. pProject  The project or configuration for the new object. If NULL the new object is created in the same project as the context's session. This parameter is for future expansion. In the first release only the session's project may be used. Flags  Modifiers for this operation. DssContextFlagTemporary The newly created object should not be saved from the context. This flag allows the user to create temporary objects (like search folders) within the context without putting them into the metadata. DssContextFlagProbeOnly Do not log error if object cannot be found externally. ppObject  Returns the instance of the new object in the context. Returns: Usual COM result code: S_OK Operation was successful. The caller may assume that *ppObject is non-NULL. E_POINTER ppObject was NULL on entry. E_INVALIDARG pKey was NULL on entry. CONTEXT_E_OBJECT_MISSING The context does not contain an instance of the object. Note that this error implies that an attempt was made to find the object. CONTEXT_E_INVALID_TYPE Some types of object cannot be imported into a context. This error is returned if an attempt is made to create an object with an invalid type. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only. Method could also return error codes from network layer or metadata server.

HRESULT IDSSObjectContext::Count (  [out, retval] Int32 *  pCount  )

Get the number of objects about which the context directly records information. Only stand-alone and managed objects are included in the count. Embedded objects and objects held by child contexts are not included. We do count missing objects. Parameters: pCount  Return the number of objects directly held by the context. Returns: Usual COM result code: S_OK Operation was successful. E_POINTER pCount was NULL on entry.

HRESULT IDSSObjectContext::EditContext (  [in, defaultvalue(0)] VARIANT_BOOL  EnsureContext, [out, retval] IDSSObjectContext   ppEditContext )

Get the edit context for this context. An edit context is a different object context with a single child (this context). Most object context methods can be used on an edit context. Objects can be checked out from the main context into its edit context. When objects are saved from the edit context they are put back into this context. An edit context can be created from an edit context. Only read-write contexts may have edit contexts. The idea is to use the edit context to perform a modal change. If the change is rejected then release the context (which will remove all objects from it). If the change is accepted then save the context back to the next level. This method is a property - calling it twice without releasing the context will return the same object. It is not safe to call an edit context and its child context from two different threads at the same time. Our assumption is that the edit context will be used by the same thread that is using the read-write context. Parameters: EnsureContext  Whether the method should construct an edit context if none previously exists. If this parameter is VARIANT_FALSE the method returns NULL if previously there was no edit context. ppEditContext  Return the edit context. Returns: Usual COM result code S_OK Success. Caller may assume ppEditContext is non-NULL, provided that EnsureContext was VARIANT_TRUE. E_POINTER ppEditContext was NULL on entry. CONTEXT_E_READ_ONLY The context is read-only, and so cannot be edited.

HRESULT IDSSObjectContext::ExecuteSearch (  [in] IDSSSearch *  pSearchObject, [in, defaultvalue(0)] Int32  pFlags, [in, defaultvalue(0)] IDSSFolder *  pExistingFolder, [out, retval] IDSSFolder   ppNewFolder )

Search objects through the context and metadata together. Parameters: pSearchObject  The search object containing search criteria. pFlags  SearchFlags to controle the search behavior. pExistingFolder  The input existing SearchFolder, if we pass this parameter, we will directly use it to store the search results. ppNewFolder  The output Search Folder, to return all the search results. Returns: Usual COM result code: S_OK Operation was successful. Caller may assume that *ppContextInfo is non-NULL.

HRESULT IDSSObjectContext::FindEmbeddedObjectByID (  [in] BSTR  ID, [in] EnumDSSObjectType  Type, [in, defaultvalue("")] BSTR  ContainerID, [in, defaultvalue(0)] EnumDSSObjectType  ContainerType, [in, defaultvalue("")] BSTR  ProjectID, [in, defaultvalue(1)] EnumDSSContextStatus  Status, [in, defaultvalue(0)] EnumDSSContextFlags  Flags, [out, retval] IDSSObjectInfo2   ppObject )

Get an instance of an embedded object specified by ID. This method behaves the same as the FindObject method. The difference between the methods is how the user specifies which object should be returned. This method can be used to obtain stand-alone objects as well as embedded objects. Parameters: ID  The ID of the requested object. Type  The Type of the requested object. ProjectID  The ID of the project for the requested object. If this parameter is NULL the object is assumed to come from the same project as the session used to obtain the object context. ContainerID  The ID of the container for the requested object. This parameter may be NULL or equal to the object ID if the object is not an embedded object. ContainerType  The Type of the container of the requested object. This parameter is ignored if the ContainerID is NULL. Status  The status required for the returned instance of the object. Flags  Modifiers for this operation. DssContextFlagProbeOnly Do not log error if object cannot be found externally. ppObject  Returns the instance of this object in the context. Could return NULL object if the context does not contain an instance of the requested object. Returns: Usual COM result code: S_OK Operation was successful. The caller may assume that *ppObject is non-NULL. E_POINTER ppObject was NULL on entry. E_INVALIDARG One or more of the parameters was an unexpected value. CONTEXT_E_OBJECT_MISSING The context (or external environment) does not contain an instance of the requested object. It is possible for an object to not exist within a context even though it does exist in the metadata. This error will also be returned if the object context gets the MDSVR_E_NO_ID error from the metadata server. OBJSVR_E_OBJECT_WRONGTYPE Either an object was found with the requested ID, but it did not have the requested Type or an object was found with the requested container ID, but it did not have the requested container type. Since IDs are not reused this indicates an error on behalf of the caller. CONTEXT_E_INVALID_TYPE Some types of object cannot be imported into a context. This error is returned if an attempt is made to import (or check-out) an object with an invalid type. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only. CONTEXT_E_READ_ONLY_IN_CHILD An attempt was made to check out an object that was imported into a (non-merged) child context. CONTEXT_E_OVERRIDDEN_DEPENDENT Cannot perform this operation because the child contains an object which has a dependent that is fixed in the parent. Method could also return error codes from network layer or metadata server. See also: FindObject

HRESULT IDSSObjectContext::FindObject (  [in] IDSSObjectInfo *  pKey, [in, defaultvalue(1)] EnumDSSContextStatus  Status, [in, defaultvalue(0)] EnumDSSContextFlags  Flags, [out, retval] IDSSObjectInfo2   ppObject )

Get an instance of the specified object. This method is used both to obtain an object and to change an object's status within the context. It requests an instance of an object and may also specify the desired status of the object. In some cases the context modifies the status of the object to satisfy the request. The status flag has the following effects: DssContextUnspecified The caller asks to see the current instance of the object in the context. If the context owns an instance of the requested object it is returned to the caller. If the object is recorded as missing from the context then the object not found error is returned. If the requested object does not already appear in the context it may be imported, if the component determines that the external instance of the object needs to be modified to maintain consistency with other objects. Otherwise the object is returned as an external object. DssContextExternal The caller asks for a current instance of the object outside of the context (and also external to any child contexts of this context). This status has no side effect on the state of the context and never returns an object from the context. It is equivilent to requesting the object from the context's source. In particular the caller cannot expect that the returned object contains no broken references. DssContextOwned The caller wants to see an object owned by the context. If the context already owns an instance of the specified object then that instance is returned. If the object is recorded as missing from the context then the object not found error is returned. Otherwise the object is imported into the context. Importing an object means that the context ensures that a read only instance of the object is available for use by the context. The context may implement this by making a copy of the given object although if possible it will reuse an object that exists outside the context. The context validates its instance of the object to make sure it has no broken references. DssContextCheckedOut The caller wants to see an instance of the object in the context that can be modified. If the object is already checked out in the context then the existing instance is returned. If the object is recorded as missing from the context then the object not found error is returned. Otherwise the context will copy the existing instance to make an instance that can be modified. DssContextReferenced If the context already has an instance of this object then we return it as it is. But if the object is not owned or checked out then the context will obtain the current external instance of the object, and store a reference to it. The object itself will still be external (it will know nothing of the context) but the context will continue to return that instance. That that a referenced object will not be able to use the context for any purpose. If the object has weak references it may be imported as usual. Other values of EnumDSSContextStatus cannot be used as an argument for this method. Parameters: pKey  Instance of the object that should be returned. The object passed into this method does not need to come from this context, or even from same source. The object may be an embedded object. Status  The status required for the returned instance of the object. Flags  Modifiers for this operation. DssContextFlagProbeOnly Do not log error if object cannot be found. DssContextFlagNoIndirectImport When fetching an object with unspecified status do not import the object. See above for the situations in which the context would normally import the object. Flag has a similar effect on referenced status. DssContextFlagNoExternal Do not attempt to get the object from the external source. The object will be reported as missing if it is not in the context (or in any linked context). ppObject  Returns the instance of this object in the context. Could return NULL object if the context does not contain an instance of the requested object. Returns: Usual COM result code: S_OK Operation was successful. The caller may assume that *ppObject is non-NULL. E_POINTER ppObject was NULL on entry. E_INVALIDARG Either pKey was NULL on entry, or Status had an unexpected value. CONTEXT_E_OBJECT_MISSING The context (or external environment) does not contain an instance of the requested object. It is possible for an object to not exist within a context even though it does exist in the metadata. This error will also be returned if the object context gets the MDSVR_E_NO_ID error from the metadata server. CONTEXT_E_INVALID_TYPE Some types of object cannot be imported into a context. This error is returned if an attempt is made to import (or check-out) an object with an invalid type. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only. CONTEXT_E_READ_ONLY_IN_CHILD An attempt was made to check out an object that was imported into a (non-merged) child context. CONTEXT_E_OVERRIDDEN_DEPENDENT Cannot perform this operation because the child contains an object which has a dependent that is fixed in the parent. Method could also return error codes from network layer or metadata server.

HRESULT IDSSObjectContext::FindObjectByID (  [in] BSTR  ID, [in] EnumDSSObjectType  Type, [in, defaultvalue("")] BSTR  ProjectID, [in, defaultvalue(1)] EnumDSSContextStatus  Status, [in, defaultvalue(0)] EnumDSSContextFlags  Flags, [out, retval] IDSSObjectInfo2   ppObject )

Get an instance of an object specified by ID. This method behaves the same as the FindObject method. The difference between the methods is how the user specifies which object should be returned. This method cannot be used to obtain embedded objects. Parameters: ID  The ID of the requested object. Type  The Type of the requested object. ProjectID  The ID of the project for the requested object. If this parameter is NULL the object is assumed to come from the same project as the session used to obtain the object context. Status  The status required for the returned instance of the object. Flags  Modifiers for this operation. DssContextFlagProbeOnly Do not log error if object cannot be found externally. ppObject  Returns the instance of this object in the context. Could return NULL object if the context does not contain an instance of the requested object. Returns: Usual COM result code: S_OK Operation was successful. The caller may assume that *ppObject is non-NULL. E_POINTER ppObject was NULL on entry. E_INVALIDARG Either ID did not contain a valid DSS Identifier, or ProjectID was neither NULL nor a valid DSS Identifier or Status had an unexpected value. CONTEXT_E_OBJECT_MISSING The context (or external environment) does not contain an instance of the requested object. It is possible for an object to not exist within a context even though it does exist in the metadata. This error will also be returned if the object context gets the MDSVR_E_NO_ID error from the metadata server. OBJSVR_E_OBJECT_WRONGTYPE An object was found with the requested ID, but it did not have the requested Type. Since IDs are not reused this indicates an error on behalf of the caller. CONTEXT_E_INVALID_TYPE Some types of object cannot be imported into a context. This error is returned if an attempt is made to import (or check-out) an object with an invalid type. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only. CONTEXT_E_READ_ONLY_IN_CHILD An attempt was made to check out an object that was imported into a (non-merged) child context. CONTEXT_E_OVERRIDDEN_DEPENDENT Cannot perform this operation because the child contains an object which has a dependent that is fixed in the parent. Method could also return error codes from network layer or metadata server. See also: FindObject

HRESULT IDSSObjectContext::GetContextInfo (  [in] IDSSObjectInfo *  pKey, [out, retval] IDSSObjectContextInfo   ppContextInfo )

Get information about a particular object in the context. This method has no side effects on the state of the context component. This method will succeed if the context records that the object is missing. If no information about the object is recorded in the context (or its children) then the context information object will report that the object has status DssContextUnspecified. The external source will not be examined. The interface returned by this method is not connected to the context. Subsequent changes to the object in the context will not be reflected on the interface. Parameters: pKey  Instance of the object whose status should be examined. The object passed into this method does not need to come from this context, or even from same source. The object may be an embedded object. ppContextInfo  Return an interface giving information about the state of the key object in the context. Returns: Usual COM result code: S_OK Operation was successful. Caller may assume that *ppContextInfo is non-NULL. E_POINTER ppContextInfo was NULL on entry. E_INVALIDARG pKey was NULL on entry.

HRESULT IDSSObjectContext::IsChildMerged (  [in] IDSSObjectContext *  pChild, [out, retval] VARIANT_BOOL *  pIsMerged )

Get whether the given context is merged with this context.. When two contexts are merged both of them can see objects in the other context. This behavior is intended to support situations where external features find it convenient to create two different contexts but in fact the contexts should contain the same objects. This method actually determines if two contexts are merged together or not. It does not matter which of them is the child, and which is the parent. A merged child of a merged child is merged with its grandparent, so this method will again report that they are merged. Similarly this method will report that a context is merged with its parent. Parameters: pChild  A descendent context of this context. pIsMerged  Return whether the child is merged with this context. Returns: Usual COM result code: S_OK Operation was successful. E_POINTER pIsMerged was NULL on entry. E_INVALIDARG pChild was NULL on entry.

HRESULT IDSSObjectContext::IsMerged (  [out, retval] VARIANT_BOOL *  pIsMerged  )

Get whether this context has been merged with some other context. There is no way to determine the parent context with which the context has been merged. This is because the context is not aware of the information. A naive implementation introduces a circular reference between the contexts (since the parent context must reference the child context). Although there are ways around this we are unlikely to expose the parent context from the child context unless a client can come up with a good reason for needing it. Parameters: pIsMerged  Whether this context has been merged with some parent context. Returns: Usual COM result code: S_OK Operation was successful. The caller may not assume that success means that *ppParent is non-NULL. E_POINTER pIsMerged was NULL on entry.

HRESULT IDSSObjectContext::IsReadOnly (  [in] VARIANT_BOOL  ReadOnly  )

Put whether this context is read-only. A read-only context cannot be modified. A user might want to make a context read-only in order to allow the context to be shared across threads without risking an AV. A constext is always created with this property set to VARIANT_FALSE. The property can be changed to VARIANT_TRUE at any time. Once the property has been set to VARIANT_TRUE it cannot be reset to VARIANT_FALSE. Parameters: ReadOnly  Whether the context should be made into a read-only context. Returns: Usual COM result code: S_OK Operation was successful. E_INVALIDARG ReadOnly was not set to VARIANT_TRUE or VARIANT_FALSE. CONTEXT_E_READ_ONLY An attempt was made to clear this property for a read-only object context. CONTEXT_E_EDIT_CONTEXT Cannot make a context read-only while it is being edited. Edit contexts are single threaded, but read-only contexts are multi-threaded. Trying to do this indicates confusion on developers part.

HRESULT IDSSObjectContext::IsReadOnly (  [out, retval] VARIANT_BOOL *  pReadOnly  )

Get whether this context is read-only. A read-only context cannot be modified. A user might want to make a context read-only in order to allow the context to be shared across threads without risking an AV. A constext is always created with this property set to VARIANT_FALSE. The property can be changed to VARIANT_TRUE at any time. Once the property has been set to VARIANT_TRUE it cannot be reset to VARIANT_FALSE. Parameters: pReadOnly  Return whether the context is read-only. Returns: Usual COM result code: S_OK Operation was successful. E_POINTER pReadOnly was NULL on entry.

HRESULT IDSSObjectContext::NewContextCollection (  [out, retval] IDSSContextCollection   oppCollection  )

Construct a new context collection based on this context. The collection is used to perform bulk load operation. That is a number of objects can be requested and then loaded together. Parameters: oppCollection  Return the new collection.

HRESULT IDSSObjectContext::NewIterator (  [in, defaultvalue(0)] EnumDSSContextFlags  Flags, [out, retval] IDSSObjectContextIterator   ppIterator )

Get an iterator to walk through the members in the object context. The iterator will include all members of the collection in the context when it was constructed. If the context is modified, new members are not guaranteed to appear in the iterator, but might appear. It is safe to modify the context during iteration, even if the modification is done from another thread. By default (and always on edit context), only immediate members are included in the iteration. Missing members are part of the iteration. Embedded objects are not included, since they are considered to be part of their containers. The iterator is intended to be used in something like a C++ for-loop. for (; Iterator.HasItem; Iterator.Advance) { ... } In otherwords HasItem should be called to check that the iterator is ready for use. Call Advance to move to the next item, if any. Parameters: Flags  Flags to modify the scope of the iteration. DssContextFlagIterateUsingEdit Return instance of object from edit context instead of the instance in this context. DssContextFlagIterateOverEdit Include objects from parent edit contexts. Note that if this flag is used with UsingEdit then only one instance of each object will be given. But without that flag each instance of edited objects will be given. DssContextFlagIterateMerged Include objects from merged contexts. This flag cannot be used on edit contexts. DssContextFlagIterateChild Include objects from child contexts. This flag cannot be used on edit contexts. DssContextFlagIterateExcludeEdited Exclude objects that are overridden in a higher edit context. When this flag is used the DssContextFlagIterateUsingEdit has no effect. DssContextFlagConsiderRecentChanges Inlcude objects recently changed by a save from an edit context. ppIterator  The new iterator. Returns: Usual COM result code: S_OK Operation was successful. The caller may assume that success means that *ppIterator is non-NULL. E_POINTER ppIterator was NULL on entry. E_INVALIDARG Returned if an attempt is made to use DssContextFlagIterateMerged, DssContextFlagIterateChild or DssContextFlagIterateOverEdit on an edit context.

HRESULT IDSSObjectContext::NewObject (  [in] EnumDSSObjectType  Type, [in, defaultvalue(0)] IDSSObjectInfo *  pProject, [in, defaultvalue(0)] EnumDSSContextFlags  Flags, [out, retval] IDSSObjectInfo2   ppObject )

Create a new object within this context with the specified object type. A newly created object always has checked out status. To save the newly created object as a stand-alone object the user must set the IDSSObjectInfo2::DestinationFolder property of the new object. Otherwise the object will be saved as a managed object. This method cannot be used to create new embedded objects. Instead new embedded objects can be created within a context be checking out the desired container and then calling IDSSEmbeddedFolder::Add on the embedded folder of the container. Parameters: Type  The type for the new object. pProject  The project or configuration for the new object. If NULL the new object is created in the same project as the context's session. This parameter is for future expansion. In the first release only the session's project may be used. Flags  Modifiers for this operation. DssContextFlagTemporary The newly created object should not be saved from the context. This flag allows the user to create temporary objects (like search folders) within the context without putting them into the metadata. ppObject  Returns the instance of the new object in the context. Returns: Usual COM result code: S_OK Operation was successful. The caller may assume that *ppObject is non-NULL. E_POINTER ppObject was NULL on entry. E_INVALIDARG Type was not value in the enumeration. E_NOTIMPL An attempt was made to create an object in an unsupported project. We hope to remove this restriction in a future release. CONTEXT_E_INVALID_TYPE Some types of object cannot be imported into a context. This error is returned if an attempt is made to create an object with an invalid type. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only.

HRESULT IDSSObjectContext::Remove (  [in] IDSSObjectInfo *  pObject, [in, defaultvalue(0)] EnumDSSContextFlags  Flags )

Remove a given object from the object context. Any object for the context is discarded. This method should be used with caution, since it could cause broken references to appear inside the context. Suppose two objects A and B are imported into a context, where A uses B. Removing B from the external environment does not effect the context. But if B is then explicitly removed from the context with this method then A will be left with a broken reference. The object is only removed from the context on which the call is made. If the object exists in two contexts (e.g. in an edit context) then the other context is not affected. Similarly the object will not be removed from a merged or child context. Parameters: pObject  The object to remove from the context. The object passed in does not need to be the same instance of the object as the instance held in the context. In fact this method will work even if the context records that pObject is missing in the context. Flags  Modifiers for this operation. DssContextFlagProbeOnly Do not log error if object cannot be found. Returns: Usual COM result code S_OK Success. E_INVALIDARG pObject was NULL on entry. CONTEXT_E_OBJECT_MISSING The object is not found in the context. Note that this means that there was no entry at all for the object. If there was a missing entry then it will be removed, and S_OK returned. CONTEXT_E_READ_ONLY The context is read-only, and so cannot be edited.

HRESULT IDSSObjectContext::RemoveChild (  [in] IDSSObjectContext *  pChild  )

This context should no longer consider the given context as a child context. This method can only be used to remove immediate child contexts of this context. Grandchild contexts can only be removed by modifying their own parents. Although we support removing a merged child context, the child will be left with no members following the removal. When a parent and child context are merged all of the member objects are moved to the parent context. Parameters: pChild  The context that should be removed from this context's list of children. Returns: Usual COM result code: S_OK Operation was successful. E_INVALIDARG pChild was NULL on entry. DSSCOM_E_OBJECT_NOT_FOUND pChild is not an immediate child of this context. CONTEXT_E_READ_ONLY The operation cannot be performed because the DSS Object Context is read-only.

HRESULT IDSSObjectContext::SaveAll (  [in, defaultvalue(0)] EnumDSSContextFlags  Flags  )

Save all changes from this context to the object source. This method saves all (non-temporary) objects checked out in this context. It does not matter if the object has been modified since it was checked out. The objects are saved with a single transaction. This method does nothing if no changes were made using this object context. A managed object is not saved if it was created in the context and the context does not contain any strong references to the managed object. An embedded object is not saved if the instance of its container in the context does not reference it (possibly indirectly). Referenced objects are not saved. The context does not consider itself to own such an object. Parameters: Flags  Modifiers for this operation. DssContextFlagSaveOverwrite Supply the DssSourceSaveOverwrite flag when saving. This will cause the save method to surpress the OBJSVR_E_CHANGED_ON_DISC error. Returns: Usual COM result code: S_OK Operation was successful. SEC_E_ACCESS_DENIED User does not have permission to save one or more objects that were modified in the context. CONTEXT_E_TEMPORARY_REFERENCE The save is forbidden since one of the objects to be saved references a temporary object. Method could also return error codes from network layer or metadata server.

HRESULT IDSSObjectContext::Source (  [out, retval] IDSSSource4   ppSource  )

Get the object source that backs up this context. This is the source from makes the objects held by the context. If the user saves changes, then this source is invoked to perform the save. Parameters: ppSource  Return the context's object source. Returns: Usual COM result code: S_OK Operation succeeded. The caller may assume *ppSource is non-NULL. E_POINTER ppSource was NULL on entry.

HRESULT IDSSObjectContext::TakeOwnership (  [in] IDSSObjectInfo *  pObject, [in, defaultvalue(0)] EnumDSSContextFlags  Flags )

Move an owned object to a given merged context. When two contexts are merged an owned object can only appear in one of the contexts. In most respects it does not make any difference which context contains the object. However the owner does make a difference when iterating through the context's objects and serializing. Occassionally it is useful to move an object between contexts. This method moves the given object (actually the owned instance of the given object - the caller does not need to provide the actual instance) to this context. No action occurs if the object already belongs to this context. The object must be a stand alone object - embedded objects are owned by the same context as their containers. Note that if the object is recorded as a missing object then it can still be moved. This method cannot be used on an edit context or a read-only context. This method does not change the status of the given object. In particular it will never look for the object in the external object source. Similarly a referenced object would be moved between contexts, but still would be a referenced object. Parameters: pObject  An instance of the object to move to this context. Flags  Modifiers for this operation. DssContextFlagProbeOnly Do not log CONTEXT_E_OBJECT_MISSING if the object is not found anywhere. Returns: Usual COM result code S_OK Success. E_INVALIDARG pObject was NULL on entry, or referenced an embedded object. CONTEXT_E_READ_ONLY The context is read-only, and so cannot be edited. CONTEXT_E_READ_ONLY_IN_CHILD The object is in a read-only child context. The child context cannot be modified to move the object. E_NOTIMPL This method is not implemented on an edit context. CONTEXT_E_OBJECT_MISSING The object is not found in the context or in any context linked to it.

HRESULT IDSSObjectContext::UserRuntime (  [out, retval] IDSSUserRuntime   ppRuntime  )

Get the user runtime for the user who made this context. All requests from the context to the object source will be made on behalf of this user. Parameters: ppRuntime  Return the context's user runtime. This property is never NULL. Returns: Usual COM result code: S_OK Operation succeeded. The caller may assume *ppRuntime is non-NULL. E_POINTER ppRuntime was NULL on entry.

---