About the Creation Container Object
New WPDObjects are created only when either the Service.CreateNewObject method or the Storage.CreateNewObject method is called. A Creation Container object is created to hold properties and data temporarily that must be set during the creation of the new object. The new object remains a Creation Container object, and is not persisted as a WPDObject until the AddChild method on the parent object is called.
Creating a WPD Automation Object
The following flowchart shows how new objects in WPD Automation are created and initialized.
Use the following steps to create a WPD Automation object.
- Identify the storage or service that the object will be stored in.
- Instantiate a Creation Container object, which is a temporary object that holds the properties and data that are used to initialize the new object. Depending on the location of the new object, use either Service.CreateNewObject(Format), or Storage.CreateNewObject(Format). The format is used by WPD Automation to determine what properties can be set. For example, the format can be "mp3" to create a container to hold properties and data for transferring an MP3 object to the device.
- Assign the properties for the new object to the Creation Container object. Depending on the capabilities of the device, objects of different formats might require different properties.
- If the new object will contain only properties, for example, a contact or a folder, skip to step 6.
- If the new object will contain binary data in addition to properties, for example, a music or image file, assign the Data property of the Creation Container object to the responseStream returned by IXMLHttpRequest. This enables data to be transferred from a Web service and stored with the new object.
- Save the new object by calling the AddChild method of the parent WPDObject object, passing in the Creation Container object. The object is not stored until this step is completed.
The following example illustrates how a child contact object is created and added to a storage. The contact object does not contain any data.
// Create a container object of the "Vcard2" format.
// This will be used to hold the properties for the new contact
// until it is added to the storage.
var container = storage.CreateNewObject("Vcard2");
// Set the value of two properties on the contact.
container.ContactDisplayName = "Bob";
container.ContactMobilePhone = "(206)555-1234";
// Write the Vcard2 contact to the storage by calling the AddChild()
// method. Here, the new object is created as a direct child of the
// storage.
var newContact = storage.AddChild(container);
When a new object contains data, the data is set through the Data property of the Creation Container object. This Data property is used to hold the IStream retrieved from the XMLHttpRequest response, as in the following example.
// Create a container object of the "mp3" format.
// This will be used to hold properties and binary data of the new
// music object until it is added to the storage.
var container = storage.CreateNewObject("mp3");
// Set the value of two properties on the music file.
container.MediaTitle = "Contoso";
container.MediaGenre = "Blues";
// Set the binary data for the mp3 file from a web service.
container.Data = xmlHttpRequest.ResponseStream;
// Write the mp3 object (with data) to the storage by calling the
// AddChild() method. Here, the new object is created as a direct
// child of the storage.
var newMp3 = storage.AddChild(container);
For more examples of using the Data property of the Creation Container while writing resource data synchronously and asynchronously, see Reading and Writing Resource Data.
Related topics