IDSSSource Interface Reference

Inherited by IDSSSource2.

List of all members.

---

Detailed Description

IDSSSource is the primary interface used in DSS COM to perform actions on the object level.

That is a client cannot manipulate the definitions of objects through this interface, but can perform most (non-type specific) actions on the object as a whole. In particular the folder hierarchy can be manipulated through the IDSSSource interface. The IDSSSource interface is used in the following circumstances:

• An instance of the IDSSSource interface is made for each user-project combination that is present on a client machine. Each instance of a DSS object carries a reference to the source through which it was made. The DSS object uses this interface as its access point to the DSS COM infrastructure. If it needs other interfaces it obtains them from the source. Where possible actions on the object are performed by redirecting them to the source.
• A DSS COM client machine uses an IDSSSource interface as its object services connection to the outside world. Each call on the interface represents a message and response that the client machine could send over the network.
• The metadata server implements an IDSSSource interface, which can be used to access and modify the metadata.

  By using the same interface in each case we ensure that we can easily remove some of the stages that are typically used to obtain object services. The diagram shows the process used to obtain information in a full-scale three-tier environment.

  Suppose we have a light client. Then the client would not cache objects, and would not have a client object manager. In this case we can plug the user directly into the network connection.

  Suppose the client is in two-tier mode. Then there is no DSS Server. We can plug the metadata server directly into the Client manager.

  Finally suppose we wanted to have a light, two-tier client (i.e. a client that loads objects from the metadata before every usage). We could implement this requirement by plugging the client directly into the metadata server.

  Unfortunately this interchangeability comes with the price that the interface has to be suitable for all of the situations in which it could be used. We expect that metadata server objects on the server will service object requests from more than one user. This means that many methods on the source interface requires its client to identify both the user and the project on which it is being called.

  However on the client machine we propose to create a separate source interface for each combination (since some object can look different depending on the user-project combination that is being used to access the objects.) So these extra parameters are surplus to requirements on the client. This should not cause too server a problem to the client since he generally does not

  call the source interface directly, preferring instead to go through the various interfaces exposed by all the DSS objects.

  In some cases there are several methods that appear to offer the similar functionality. Generally we expect that the user uses one method when calling the client machine object manager and that the object manager uses the other method when passing the request over the network.

  An object server has more methods than just those defined in the IDSSSource interface. These additional methods appear in the IDSSSourceAdvanced interface. The methods in this interface are those that we expect to be useful to an application author. The other interface has methods that are used when sending messages between one machine and another. In particular it uses the IDSSObjectCollection interface, which makes it easy serialize a set of objects.

Public Member Functions
HRESULT	Administrator ([out, retval] IDispatch ppAdministrator)
	Return a special administrator interface for this source.
HRESULT	Configuration ([out, retval] IDSSConfiguration ppConfiguration)
	For both a project and a configuration source this property returns the configuration object used to define the configuration.
HRESULT	CopyObject ([in] IDSSObjectInfo *pOriginal,[in, defaultvalue(0)] IDSSFolder *pFolder,[in, defaultvalue("")] BSTR Name,[in, defaultvalue(0)] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData,[out, retval] IDSSObjectInfo ppCopy)
	Copy an object into a new folder.
HRESULT	DeleteObject ([in] IDSSObjectInfo *pObject,[in, defaultvalue(0)] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData)
	Delete an object.
HRESULT	ExecuteCommand ([in] EnumDSSSourceCommands pCommand,[in, optional] VARIANT *pIn,[in, defaultvalue(0)] Int32 iFlags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[out, retval] VARIANT *pOut)
	Perform a miscellaneous object source level command.
HRESULT	ExecuteSearch ([in] IDSSSearch *pSearchObject,[in, defaultvalue(0)] Int32 FirstObject,[in, defaultvalue(0)] IDSSFolder *pExistingFolder,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData,[out, retval] IDSSFolder ppNewFolder)
	Perform a search on objects supplied by this source.
HRESULT	FindObject ([in] BSTR Id,[in] EnumDSSObjectType Type,[in, defaultvalue(0)] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData,[out, retval] IDSSObjectInfo ppObject)
	Obtain a particular object's definition/info.
HRESULT	LoadSchema ([in] EnumDSSLoadSchema SchemaParts,[in] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData)
	Loads schema level objects into memory.
HRESULT	MoveObject ([in] IDSSObjectInfo *pObject,[in] IDSSFolder *pFolder,[in, defaultvalue(0)] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData)
	Move an object to a new folder.
HRESULT	NameScope ([in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in] Int32 NameScope)
	The uniqueness property on names in this project.
HRESULT	NameScope ([in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[out, retval] Int32 *pNameScope)
	The uniqueness property on names in this project.
HRESULT	NewObject ([in] EnumDSSObjectType Type,[in, defaultvalue(0)] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[out, retval] IDSSObjectInfo ppObject)
	Create a new object in a folder.
HRESULT	Project ([out, retval] IDSSProject ppProject)
	The project (if any) associated with this source.
HRESULT	RefreshObject ([in] IDSSObjectInfo *pObject,[in, defaultvalue(0)] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData)
	Reload an object, and replace the version in cache.
HRESULT	ReplaceDependents ([in] IDSSCollection *pObjects,[in] VARIANT *pOriginal,[in, optional] VARIANT *pReplaceWith,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime)
	This method performs a search and replace of dependencies within a list of DSS Objects.
HRESULT	Root ([in, defaultvalue(DssRootProject)] EnumDSSRootType Type,[in, defaultvalue(0)] Int32 Flags,[out, retval] IDSSFolder ppRoot)
	The root folder of the persisted hierarchy.
HRESULT	SaveObject ([in] IDSSObjectInfo *pObject,[in, defaultvalue(0)] IDSSFolder *pFolder,[in, defaultvalue(0)] EnumDSSSourceFlags Flags,[in, defaultvalue(0)] IDSSUserRuntime *pUserRuntime,[in, defaultvalue(0)] Int32 Cookie,[in, defaultvalue(0)] Int32 UserData,[out, defaultvalue(0)] IDSSObjectInfo ppCurrent)
	Persist a version of an object.
HRESULT	Schema ([out, retval] IDSSSchema ppSchema)
	The schema in use by this source.
HRESULT	Separator ([in] BSTR Separator)
	The character used to separate folder names in a path name.
HRESULT	Separator ([out, retval] BSTR *pSeparator)
	The character used to separate folder names in a path name.

---

Member Function Documentation

HRESULT IDSSSource::Administrator (  [out, retval] IDispatch   ppAdministrator  )

Return a special administrator interface for this source. Every source should have an administrator interface, which is an interface with methods specific to the type of the source (e.g. object server, metadata server etc.). This interface is returned via this read only property. This call is only useful in an environment like VB that can do run time binding. In C++ you should just query for the relevant interface. This means you need to know the type of the source in advance. Parameters: ppAdministrator  The administrator interface associated with this source. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::Configuration (  [out, retval] IDSSConfiguration   ppConfiguration  )

For both a project and a configuration source this property returns the configuration object used to define the configuration. This is a read-only property. Parameters: ppConfiguration  The configuration object used to define the configuration. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::CopyObject (  [in] IDSSObjectInfo *  pOriginal, [in, defaultvalue(0)] IDSSFolder *  pFolder, [in, defaultvalue("")] BSTR  Name, [in, defaultvalue(0)] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData, [out, retval] IDSSObjectInfo   ppCopy )

Copy an object into a new folder. Make a new object, populating its entire definition from an existing object. We allow the user to specify a new name, and folder for the new object. There are 3 kinds of copy: Local copy, persisted copy, and exact copy. Look at Usage of DSS Filing System for detailed explanation. We do not permit Copy between different kind of objects. Parameters: pOriginal  The object being copied. pFolder  The folder in which the copy should be placed. NULL creates the copy in the Object Server cache but does not persist it/ Name  The name for the copy. NULL or empty string appends some standard string. Flags  Control the behavior of the copy. pUserRuntime  User on whose behalf we copy the object. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. ppCopy  A reference to the new object created by the Copy. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::DeleteObject (  [in] IDSSObjectInfo *  pObject, [in, defaultvalue(0)] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData )

Delete an object. This method deletes an object. The default behavior is to delete an object from the metadata and from the local object. The deletion fails if another object (not counting the folder that contains this object) is dependent on this object or this object is a non-empty folder except the flag DssSourceDeleteForce is set. Flags are used to modify its behavior. It is possible to restrict the deletion to the local object server (in which it does not effect the metadata at all, and the object is not truly deleted, only the cached instance get deleted). It is also possible to change the behavior if we find that the object is used by another object. If the object cannot be deleted because the object is in use, then the usual search mechanism can be used to find the objects that depend on this object. Parameters: pObject  The object to be deleted. Flags  Controls the behavior of the delete operation: pUserRuntime  User on whose behalf we delete the object. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. Returns: Usual COM result code: S_OK DSSCOM_E_DELETE_DEPOBJ Unable to delete the object because the object has dependent objects. Set the DssSourceDeleteForce flag to delete the object any way.

HRESULT IDSSSource::ExecuteCommand (  [in] EnumDSSSourceCommands  pCommand, [in, optional] VARIANT *  pIn, [in, defaultvalue(0)] Int32  iFlags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [out, retval] VARIANT *  pOut )

Perform a miscellaneous object source level command. This method executes a generic command on the object source. This is used to implement miscellaneous features that apply to an object source as a whole. For example it can be used to determine if a source supports a specific command. The main purpose of this method is to allow us to extend the functionality of the IDSSSource interface in a clean fashion. This table lists the possible commands. It is likely that more commands will be added in future releases. Constant Value Comment DssSrcCmdSupport 0 Determines if the source is able to handle a specific command pIn = Command caller which interests caller pOut = 'True' if command is supported If necessary a 3-tier client will call its server to determine if the server supports the command. DssSrcCmdVersion 1 Determine the version of this source. pOut = Version supplied as a long number By convention the thousands figure in this number corresponds to the major version number. Later versions will have higher numbers. On a 3-tier client the number returned is the minimum of the client and server's version. DssSourceCommandMDVersion 2 Determine the version of the underlying MD pOut = Version supplied as a long number By convention the thousands figure in this number corresponds to the major version number. Later versions will have higher numbers. DssSrcCmdRefreshProperties 3 Refresh the property sets and property groups on this source. Object sources cache locally the property sets and groups inside a project, since they rarely change. If a user has changed them, then this command must be called to see the changed properties on objects. DssSrcCmdNameLength 4 Return the maximum allowed length of an object Name in this object source. pOut = Maximum allowed object name Because of different character encoding schemes supported by different repositories the maximum allow length of a name depends on the underlying metadata platform. DssSrcCmdPurge 5 Purge all objects from an object cache. Flags: - DssSourcePurgeClient purges client side cache DssSourcePurgeServer purges server side cache DssSrcCmdLocalVersion 6 Determine the local version of this source. pOut = Version supplied as a long number By convention the thousands figure in this number corresponds to the major version number. Later versions will have higher numbers. This method never makes a network call DssSrcCmdRemoteVersion 7 Determine the version number of the object source in the server. pOut = Version supplied as a long number By convention the thousands figure in this number corresponds to the major version number. Later versions will have higher numbers. This command is only supported by a 3-tier client. DssSrcCmdDiagnostics 8 Reserved for future expansion. DssSrcCmdEncryptionLevel 9 Determine the preferred encryption level, i.e. the level of encryption that the server will use for new passwords in the metadata. -1 means no encryption, 0 means standard encryption DssSrcCmdConfigurationVersion 10 Determine the version id of the configuration object DssSrcCmdMembership 11 Notify the server that the members of a user group object have changed. This forces the server to rebuild the user group membership information. DssSrcCmdRefreshDBConnectionMap 12 Notify the server that the contents of the db connection map for a project have changed. This forces the server to rebuild the connection map for the project into which the user is currently logged in. An attempt to issue this command while logged into the configuration will result in an error. DssSrcCmdReadMDProperty 13 Read a metadata system property from the DSSMDSYSPROP table: pIn - String with the name of the property to read pOut - String with the value of the property in the metadata, VT_EMPTY if property does not exist in the metadata. Metadata system property names are not case sensitive. This command requires the caller to have the UseServerAdmin privilege. DssSrcCmdWriteMDProperty 14 Write a metadata system property into the DSSMDSYSPROP table: pIn - String containing both the name and the value of the property to be written separated with a semicolon. If the string does not contain a semicolon the entire string will be assumed to be the property name and the value will default to an empty string. The property value can contain embedded semicolons. Metadata system property names are not case sensitive. This command requires the caller to have the UseServerAdmin privilege. DssSrcCmdDeleteMergeUser 15 Delete a user and merge it into another one. pIn - String containing two IDs, separated by ':' = "ID_MergeTo:ID_MergeFrom" DssSrcCmdReadRDBMSPassword 16 Read user's RDBMS password pIn - String representing the user's ID pOut - String representing the (decrypted) password. DssSrcCmdWriteRDBMSPassword 17 Write user's RDBMS password pIn - String containing the user's ID and the password, in this order and separated by ';'. DssSrcCmdPurgeAllLinkCaches 18 Purge all link item caches related (registered) to the project/configuration. Flags: - DssSourcePurgeClient purges the client side link caches related to the project/config DssSourcePurgeServer purges the server side link caches related to the project/config DssSrcCmdPurgeLinkCache 19 Purge the link item cache(s) associated with a link object specified by its ID. If there are more than one link item cache related to such an object, all of them will be purged. (The only way to purge the link cache of a specific link object instance is trough the link object's IDSSLink2 interface.) Flags: - DssSourcePurgeClient purges the client side cache(s) related to the given link object DssSourcePurgeServer purges the server side cache(s) related to the given link object pIn - String representing the link object ID. Parameters: pCommand  An enumeration constant that specifies which command the user wishes to perform. pIn  An input parameter. The meaning of this parameter depends on the value of pCommand. iFlags  Usual source flags (if relevant) pUserRuntime  Identifies the user. pOut  An output value. The meaning of this parameter depends on the value of pCommand. Returns: Usual COM result code: S_OK E_NOTIMPL Source is unable to handle the given value of pCommand E_INVALIDARG Unexpected value supplied for pIn E_POINTER pOut was NULL for a command that returns an output

HRESULT IDSSSource::ExecuteSearch (  [in] IDSSSearch *  pSearchObject, [in, defaultvalue(0)] Int32  FirstObject, [in, defaultvalue(0)] IDSSFolder *  pExistingFolder, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData, [out, retval] IDSSFolder   ppNewFolder )

Perform a search on objects supplied by this source. This call will find first-class objects that satisfy conditions specified in the IDSSSearch interface. For more information, refer to the specification of IDSSSearch::Execute. Parameters: pSearchObject  The condition of objects to be found. FirstObject  Index of first object to be sent back to user. pExistingFolder  Existing folder to be appended. pUserRuntime  Identifies the user. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. ppNewFolder  New folder created by Object Server or the same as existing folder if provided. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::FindObject (  [in] BSTR  Id, [in] EnumDSSObjectType  Type, [in, defaultvalue(0)] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData, [out, retval] IDSSObjectInfo   ppObject )

Obtain a particular object's definition/info. Load an object given only by an identifier. By default the entire object is loaded, but a Flags setting may be used to obtain just the object information. This call is unlikely to be useful to ordinary users, since it is unusual for a user to obtain an object identifier without also obtaining the object information. Once the user has the object information he can obtain the entire object by making any call on the object which requires the definition to be loaded, or by using the RefreshObject method if a callback is required. However the call is needed to implement the object server. It could also be useful to an application that records object ids independently of the object server, and then at a later times wants to recover the objects that used these Ids. This call should only be used to obtain an existing object. The object may exist locally or remotely. This call may not be used to create a new object. We do not want users to be able to make objects with their own choice of DSS_ID. If a request is made to find an object, but Flags does not ask for any additional information about the object at all, then the object server should still check that an object of the given ObjectID exists in its outsource, even though it isn't required to load anything at all from the object. We implement this by always loading the browse information. Parameters: Id  The Identifier of the required object. Type  The type of the required object. (Needed in case an empty shell needs to be manufactured.) Flags  Controls the behavior of the operation. pUserRuntime  User on whose behalf we find the object. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. ppObject  An instantiation of an object with the required identifier. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::LoadSchema (  [in] EnumDSSLoadSchema  SchemaParts, [in] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData )

Loads schema level objects into memory. Use this call to load multiple schema level objects into the object server. This is useful since we want to ensure that schema level objects are available when needed. The schema returned by the Schema property is used to obtain the list of the required objects. The EnumDSSLoadSchema enumeration has the following values: Constant Value Comment DssSchemaAttributeForms 0x00000001 Load all attribute forms DssSchemaAttributes 0x00000002 Load all attributes DssSchemaColumns 0x00000004 Load all columns DssSchemaFactGroups 0x00000008 Load all fact groups DssSchemaFacts 0x00000010 Load all facts DssSchemaFunctions 0x00000020 Load all functions DssSchemaHierarchies 0x00000040 Load all hierarchies DssSchemaRoles 0x00000080 Load all roles DssSchemaTables 0x00000100 Load all tables DssSchemaAll 0x000001FF Load in all the schema objects Parameters: SchemaParts  A bit vector representing which of the different types of schema dependents to load. Flags  Controls the behavior of the operation. The following flags are recognized: DssSourceDefn, DssSourceBrowser, DssSourceDates, etc. - objects' definition (or browse information, dates, etc.) should be available on the local machine by the end of the call. DssSourceTotalObject - All of the objects' parts should be on the local machine by the end of the call pUserRuntime  Identifies the user. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::MoveObject (  [in] IDSSObjectInfo *  pObject, [in] IDSSFolder *  pFolder, [in, defaultvalue(0)] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData )

Move an object to a new folder. Moves the object into a new folder. The change is passed on to the underlying source. Suppose that X is a general object, and that F is a folder. If the client executes X.Parent = F then the object X will implement the call by executing the following equivalent call: Call X.Source.MoveObject(X, F) This call should reset the Parent property of X. Note however that it cannot do this in the obvious fashion, since this would create an infinite loop. Here we see one of the reasons why it is a good idea for sources to create their own objects. It enables the source to directly address the Parent property of the objects that it created. Parameters: pObject  The object that should be moved. pFolder  The new folder in which the object should be placed. Flags  Controls the behavior of the operation. pUserRuntime  User on whose behalf we move the object. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::NameScope (  [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in] Int32  NameScope )

The uniqueness property on names in this project. This property has not been implemented. Records the scope through which names in the project must be unique. It is a bit vector. The default value does not place any uniqueness requirement on names. Since DSS COM identifies objects by their ObjectID, there is no intrinsic reason why we couldn't give multiple objects the same name. A NameScope value is obtained by combining zero or more of the following enumeration values. Constant Value Comment DssScopeProject 1 Name is unique up to project. DssScopeFolder 2 Name is unique up to folder. DssScopeOwner 4 Name is unique up to owner. DssScopeObject 8 The name is unique up to object. If NameScope is large, then there are fewer restrictions on the names of objects. NameScope = 0, requires that each name can only be used once in a master project. NameScope = 1, permits a name to appear more than once in a master project, but only once in each project. NameScope = 2, requires a folder (in the master project) to contain objects with distinct names, whereas NameScope = 3 lets names be repeated provided that they are in different projects. If NameScope >= 8 then there are no restrictions on names. This is the default case. Parameters: pUserRuntime  Identifies the user. NameScope  Proposed new NameScope value. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::NameScope (  [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [out, retval] Int32 *  pNameScope )

The uniqueness property on names in this project. This property has not been implemented. Records the scope through which names in the project must be unique. It is a bit vector. The default value does not place any uniqueness requirement on names. Since DSS COM identifies objects by their ObjectID, there is no intrinsic reason why we couldn't give multiple objects the same name. A NameScope value is obtained by combining zero or more of the following enumeration values. Constant Value Comment DssScopeProject 1 Name is unique up to project. DssScopeFolder 2 Name is unique up to folder. DssScopeOwner 4 Name is unique up to owner. DssScopeObject 8 The name is unique up to object. If NameScope is large, then there are fewer restrictions on the names of objects. NameScope = 0, requires that each name can only be used once in a master project. NameScope = 1, permits a name to appear more than once in a master project, but only once in each project. NameScope = 2, requires a folder (in the master project) to contain objects with distinct names, whereas NameScope = 3 lets names be repeated provided that they are in different projects. If NameScope >= 8 then there are no restrictions on names. This is the default case. Parameters: pUserRuntime  Identifies the user. pNameScope  Proposed new NameScope value. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::NewObject (  [in] EnumDSSObjectType  Type, [in, defaultvalue(0)] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [out, retval] IDSSObjectInfo   ppObject )

Create a new object in a folder. This call creates a new object within this object server. The object is not populated. A client of the server uses this call if it wants to make a new object. The object is not saved until the client calls the SaveObject method. The new object is assigned a fresh GUID by the object server. Creation of locale objects is not supported by this call. Please refer to IDSSSource8::NewLocale instead. Parameters: Type  The type of the new object. Flags  Modify the behavior of the NewObject pUserRuntime  User on whose behalf we create the new object. ppObject  The new object that was created by the call. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::Project (  [out, retval] IDSSProject   ppProject  )

The project (if any) associated with this source. For a project source this property returns the project object that defines the project. NULL for a configuration level source. This property is read only since it is set when the source is constructed. Parameters: ppProject  The project associated with this source. NULL if this source is not project specific. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::RefreshObject (  [in] IDSSObjectInfo *  pObject, [in, defaultvalue(0)] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData )

Reload an object, and replace the version in cache. The object server reloads the object from persistent storage. The version of the object stored in the cache is modified to agree with the persistent storage. If the object server is maintaining any secondary storage media, then they should be altered as well. We expect that the user issues the call if he believes that the persisted form of the object is different from the current form of the object. This call can be supported by sources, like the metadata server, that are not able to construct objects. RefreshObject can also be used to load an unknown object. The object server can respond to FindObject by first constructing an object with no contents, but the correct ObjectID. Then it can pass this object to the underlying source via a call to RefreshObject. The underlying source has to refresh it, by loading in the contents. The advantage of this approach is that the underlying source does not need to create the new object. Parameters: pObject  The object that should be refreshed. Flags  Controls the behavior of the refresh operation: pUserRuntime  User on whose behalf we refresh the object. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. Returns: Usual COM result code: S_OK

HRESULT IDSSSource::ReplaceDependents (  [in] IDSSCollection *  pObjects, [in] VARIANT *  pOriginal, [in, optional] VARIANT *  pReplaceWith, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime )

This method performs a search and replace of dependencies within a list of DSS Objects. It is given a collection of DSS Objects, and a search-object. The method then searches the collection of objects looking for direct references to the search-object. Each reference that it finds is either replaced with a reference to a given replace-object, or (if there is no replace-object) removed entirely. The collection of object is passed as a DSS Collection (IDSSCollection interface). This kind of collection holds references to specific instances of objects. It is the instance of the objects in the collection that are modified if a change is needed. If an object in the collection does not contain any reference to the search-object then it is not changed. References from objects embedded inside the object in the collection are treated in exactly the same manner. The objects in the collection must be modifiable, and the caller must have write-access on each object. The modification, if any, is only performed in memory. The metadata is not changed. If the caller wants to persist the change to MD, then the caller must make additional API calls. The search-object must be a stand-alone object. The replace-object must also be a stand-alone object, and must have the same type as the search-object. If no replace-object is provided then the references to the search-object are removed without being replaced by anything. When deleting a reference we attempt to remove it in such a way that the object that remains is still a valid object. Sometimes this is not possible though. It is the caller's responsibility to ensure that the replace-object can be cleanly substituted for the search-object. In some cases (for example replacing a custom group with a filter, or introducing a cyclic dependency) it is possible that the search and replace will result in objects that cannot be used. Parameters: pObjects  DSS Collection of objects. If the collection is empty then the method does nothing. Must not be NULL. pOriginal  A variant containing a reference to the search-object. The search object must be non-null, and may not be an embedded object. pReplaceWith  A variant containing a reference to the replace-object. May be NULL, or contain an empty variant to indicate no object is needed. pUserRuntime  Identifies the user making the call (needed for securiy checks). On a client session we will default to using the session's user runtime if NULL is passed in. Returns: Usual COM result code: S_OK Method was successful. E_INVALIDARG There was a problem with the arguments. This error is returned if either pObjects or pOriginal is NULL, or if the variants do not contain a reference to a DSS Object. SEC_E_ACCESS_DENIED Caller does not have sufficient access. This method requires Use access on the replace-object (if any) and Write access on the objects in the object collection. OBJSVR_E_OBJECT_WRONGTYPE We detected attempt to replace an object with an object of a different type. DSSCOM_E_NOTINITIALIZED The method was called on uninitialized object server.

HRESULT IDSSSource::Root (  [in, defaultvalue(DssRootProject)] EnumDSSRootType  Type, [in, defaultvalue(0)] Int32  Flags, [out, retval] IDSSFolder   ppRoot )

The root folder of the persisted hierarchy. This read-only property returns a reference to the root folder of the persisted hierarchy in the source. This property is very important, since it is the only way to get a DSS object from a source without knowing its ObjectID in advance. (Schema objects can be obtained from the schema, but this will not help the user obtain report or template objects.) Once a client has a reference to the root folder, he can obtain all the other objects in the project by browsing below the root folder. In general it would not be good idea to load all these objects onto the client machine. The flags property may be used to distinguish between resource tree and schema/application object tree. Parameters: Type  Point out which root the user would like to get: - DssRootProject - root folder of the project, NULL for a configuration level source. DssRootConfiguration - root folder of the configuration. Flags  Reserved for future use. ppRoot  A reference to the root folder. Returns: Usual COM result code: S_OK OBJSVR_E_NO_PROJECT This call can only be made in a project specific instantiation of the object server (when type is DssRootProject).

HRESULT IDSSSource::SaveObject (  [in] IDSSObjectInfo *  pObject, [in, defaultvalue(0)] IDSSFolder *  pFolder, [in, defaultvalue(0)] EnumDSSSourceFlags  Flags, [in, defaultvalue(0)] IDSSUserRuntime *  pUserRuntime, [in, defaultvalue(0)] Int32  Cookie, [in, defaultvalue(0)] Int32  UserData, [out, defaultvalue(0)] IDSSObjectInfo   ppCurrent )

Persist a version of an object. The SaveObject method passes a given object back to the metadata server. If the object already exists in metadata it is overridden with the object that is here. If the object does not exist in the metadata, then this creates a new object. Please look at DSS Filing System for a detailed explanation of this method. Parameters: pObject  The instance that we want to save into persistent storage. pFolder  The folder where the object saves to. If the folder provided is NULL, we either save the object to its original folder (if the object has been persisted before), or save the object as a root (if the object was not persisted). Flags  Control the behavior of the save. Flags not listed here have no effect on the save: pUserRuntime  User on whose behalf we save the object. Cookie  Identifies the callback site, if a callback response is requested. UserData  Caller's reference number, used by the caller to identify this call. ppCurrent  May be NULL on entry, if caller has no interest in this result. Returns NULL or an object instance with the same ID as pObject. If a call fails OBJSVR_E_CHANGED_ON_DISC, then this is a local instance of the current object in the metadata. Returns: Usual COM result code: S_OK OBJSVR_E_NAMECLASH The object cannot be persisted because its name is already in use. This message may be returned when the project is configured to use globally unique names. OBJSVR_E_CHANGED_ON_DISC The object that we would overwrite has a different VersionID to the object we started with. MDSVR_E_OBJECT_LOCKED The object has been lock from a different session, or has been permanently locked.

HRESULT IDSSSource::Schema (  [out, retval] IDSSSchema   ppSchema  )

The schema in use by this source. The schema used by this object server. The value of this property depends on the project that was selected when the object server was created. This call returns the schema object whose DSS_ID is given by the Project object. This call cannot function if there is no project object. Returns: Usual COM result code: S_OK OBJSVR_E_NO_PROJECT This call can only be made in a project specific instantiation of the object server.

HRESULT IDSSSource::Separator (  [in] BSTR  Separator  )

The character used to separate folder names in a path name. This property gives the character that will be inserted between folder names when constructing a path to an object. It defaults to the backslash character (\). Only the characters \ and / may be used as separators. We want to keep the list short since we have to exclude separator characters from all names. Returns: Usual COM result code: S_OK OBJSVR_E_INVALID_SEPARATOR The new separator is not acceptable. The error message should state that only \ and / are valid separator characters.

HRESULT IDSSSource::Separator (  [out, retval] BSTR *  pSeparator  )

The character used to separate folder names in a path name. This property gives the character that will be inserted between folder names when constructing a path to an object. It defaults to the backslash character (\). Only the characters \ and / may be used as separators. We want to keep the list short since we have to exclude separator characters from all names. Returns: Usual COM result code: S_OK OBJSVR_E_INVALID_SEPARATOR The new separator is not acceptable. The error message should state that only \ and / are valid separator characters.

---