Requirements for Plug-in Data Objects (Windows Embedded CE 6.0)
1/6/2010
Plug-in data objects must be derived from the PluginData class. The PluginData class provides standard ways to enumerate, present, and accept data, and it provides a standardized way to get data from the device. For more information, see Remote Tools Framework Native API.
Typically, for each node that has data associated with it in the Remote Tools Shell TreeView, a plug-in developer creates one plug-in data object. Some nodes are used only as organizational labels, so they have no data. For more information, see Requirements for Plug-in Data View Objects.
At a minimum, you must implement the following methods for each plug-in data object.
- Constructor
- OnGetData
- OnRenderGeneric
Constructor Method
The following code example shows how to implement the requirement that the Constructor method must call the base class.
public MyData(
Plug-inComponent host,
string guid
)
: base(host, guid)
{
}
OnGetData Method
The Remote Tools Framework automatically establishes a connection to a target device and opens up a command transport to that device. To tell a plug-in data object to get data from the device, call the OnGetData method.
The plug-in data object has a base property called Commandtransport that you can use. In the OnGetData method, you must build a CommandPacket object, and then use that object to call the ProcessCommand method of the CommandTransport.
At this point, data passes to the device, and then the device-side code runs. The assumption at this point is that the device-side code runs synchronously and the ProcessCommand method returns a CommandPacket object.
You must now take the values from the command packet and store them in your own data structures. After the data has been successfully stored, set the INITIALIZED property of the data object to TRUE. This refreshes the view panes associated with the data object.
If you want to force the views associated with your data object to refresh, call the RenderViews method with an object hint as a parameter. You can choose to define the hint parameter, or leave it null. For more information about the RenderViews method, see the Remote Tools Framework Native API.
The following code example from the SimplePlugin project shows how to implement the OnGetData method. OnGetData is configured to receive four pieces of data: a WORD, a DWORD, a String, and an array of bytes.
public override void OnGetData()
{
// Populate a command object (command value of 1)
CommandPacket sendCommand = new CommandPacket();
sendCommand.CommandID = 1;
// Process the command
CommandPacket receivedCommand =
base.CommandTransport.ProcessCommand(
sendCommand,
this
);
// Place results in data items
// The device side app builds and returns a packet
// with a WORD, a DWORD, a string, and 4 bytes,
UInt16 w = receivedCommand.GetParamaterWORD();
strings.Add(w.ToString()); // strings is just an arraylist
UInt32 dw = receivedCommand.GetParamaterDWORD();
strings.Add(dw.ToString());
string s = receivedCommand.GetParamaterString();
strings.Add(s);
byte[] bytes = receivedCommand.GetParamaterBYTES();
string fmt = "";
foreach (byte b in bytes)
{
fmt = fmt + b.ToString() + " ";
}
strings.Add(fmt);
// Set the Initialized property to let the Remote Tools
// Framework know that the data is ready for display.
// Setting Initialized to true signals any views
// to refresh.
this.Initialized = true;
}
OnRenderGeneric Method
The Remote Tools Framework frequently uses a GenericDataAcceptor variable to ask the plug-in data object to enumerate its data. The plug-in data object uses an OnRenderGeneric method to accomplish the task. For more information about the Remote Tools Framework, see the Remote Tools Framework Native API.
In the OnRenderGeneric method, your data object must call the acceptor’s AddItem method for each piece of data, in the format of a category, a description, and a value. These are all strings.
In the SimplePlugin project, the data is an array of strings. For more information about the project, see SimplePlugin Sample.
The following code example from the SimplePlugin project shows how to enumerate the strings into the data acceptor.
public override void OnRenderGeneric(
GenericDataAcceptor dataAcceptor
)
{
string Category = "My category";
for (int i = 0; i < this.strings.Count; i++)
{
dataAcceptor.AddItem (
Category,
"String #" + i.ToString(),
this.strings[i].ToString()
);
}
}