MDS 7.3 COM documentation

NEW COM FUNCTIONS:
------------------

Import Project from XML


IApplication.Projects.ImportFromXML( [in] BSTR strName, [out,retval] IProject** pProject );

This function takes a string which is the full path to a project xml file, for example "c:\projects\example.ppcx". A
Project is imported and opened. The resulting project is returned in the pProject return pointer.

Example (in c#):
	var project = application.Projects.ImportFromXML(@"c:\path\to\Project.ppcx");

IProjects.GetProjectByFileName([in] BSTR strFilename, [out,retval] IProject** ppProject );

Return a project object for an open project with the given file name. The filename can be just the project filename, (for example, "Courier.ppc") or a full path (such as "c:\projects\Courier.ppc"). The filename and path are not case sensitive.

Example (in c#):
	var project = application.Projects.GetProjectByFileName(@"c:\path\to\Project.ppc");


IProjects.GetProjectByUnique([in] DWORD nUnique, [out,retval] IProject** ppProject );

With the give unique identifier in nUnique, return the a project object in pProject. The project must be open, otherwise an error is returned.

Example (in c#):
	var project = application.Projects.GetProjectByUnique(12345678);


ISession.Marked

The marked state of a session can be accessed (get and set) using the Marked property.

Example (in c#):
	var session = application.Projects.Database.Item(1); // get first session
	session.Marked = !session.Marked; // toggle marked state.


IApplication.ListProjectsOnDevice(sUnitID)

If the device with the specified Unit ID is connected it will be sent a command to list projects installed. If the device understands the message, it will respond, and the list of projects will be sent to the management delegate object if it has been set.

The device must be connected to send the command or this has no effect.

Example (in c#):
	application.ListProjectsOnDevice("device01");


IApplication.DisconnectDevice(sUnitID)

Forces the connection to the specified device to be closed.

The device must be connected to send the command or this has no effect.

Example (in c#):
	application.DisconnectDevice("device01");


IApplication.RemoveAllProjectsFromDevice(sUnitID)

This sends a network message to remove all projects to the specified device. This is intended to be used in a BYOD scenario where an employee or contractor is no longer working with MDS and the operators wish to remove the projects and all project data from the device. This is a destructive operation.

The device must be connected to send the command or this has no effect.

Example (in c#):
	application.RemoveAllProjectsFromDevice("device01");


IProject.RemoveFromDevice(sUnitID)

This sends a network command to remove a specific project from a device. This is intended to be used by customers who move a device from one project to another and wish to automate the step of removing a project from specific devices.

When the device confirms the operation, the management delegate method IManagementDelegate.OnDeviceRemovedProject is called with the Unit ID of the device and the name and unique identifier of the project.

Example (in c#):
	var project = application.Projects.Item(1); // get first project
	project.RemoveFromDevice("device01");


Interface: IManagementDelegate

This is a COM interface that external applications can implement to receive notifications about device activity, such as connect, disconnect, submit sessions, and so on. An external application must implement all methods in the interface.

This is an expert feature, and is not intended for casual users to use.

Using the management interface requires great care. Some challenges with using the management delegate include ensuring that the MDS application is already running, and that programmer does not leave any dangling references to COM objects which can cause memory leaks and subsequent crash of MDS.

Once it is published as a supported feature, then no breaking changes can be made to the inteface. 

This is set using the IApplication.SetManagementDelegate method and can be cleared with the IApplication.ClearManagementDelegate() method.



NEW DATA SCRIPT CALLBACKS:
--------------------------

OnDeviceConnected(sUnitId)

This callback is invoked when a device connects. Each project that implements this callback in its Datascript will have the callback invoked with a string of the device's Unit ID.

OnSessionIncomingDeferred()

This callback is the same as the OnSessionIncoming, except that it is invoked after a delay. It is only safe to send the session back to the same device from this callback. Using the OnSessionIncoming callback to send a session back to the same device will result in that session being lost. OnSessionIncomingDeferred solves this problem by being invoked after the device completes the send operation. One caveat to this is that the callback occurs after any automatic exports so changes to the session itself will not be present in those exports.



PROTOCOL CHANGES:
-----------------

The following commands are new in the MDS protocol. Older clients will ignore these commands, and issue no response as per the protocol specification.


Protocol: server query projects installed on device (accessible via COM) -- implemented in iOS & Android:

Using Application.ListProjectsOnDevice(sUnitId) replies are delivered as IManagementDelegate.OnDeviceSentProjectList callbacks. The callback is passed an array of project names and an array of project unique identifiers.

Protocol: server remove specific project from device (accessible via COM) -- implemented in iOS & Android:

This is a network message to remove a specific project from a device. This is intended to be used by customers who move a device from one project to another and wish to automate the step of removing a project from specific devices.

When the device confirms the operation, the management delegate method IManagementDelegate.OnDeviceRemovedProject is called with the Unit ID of the device and the name and unique identifier of the project.

Protocol: server remove all projects from device (accessible via COM) -- implemented in iOS & Android:

This is a network message to remove all projects on a device. This is intended to be used in a BYOD scenario where an employee or contractor is no longer working with MDS and the operators wish to remove the projects and all project data from the device. This is a destructive operation.

IManagementDelegate.OnDeviceConfirmedRemoveAllProjects is the callback received when a device processes this network message.