Transferring a Properties-Only Object to the Device

While the example in the previous topic demonstrated the creation of content on a device consisting of both properties and data, this topic focuses on the creation of a properties-only object.

Property-only transfers are accomplished using the interfaces described in the following table.

The TransferContactToDevice function in the sample application's ContentTransfer.cpp module demonstrates how an application could transfer contact information from a PC to a connected device. In this particular sample, the transferred contact name is a hard-coded "John Kane" and the transferred contact phone number is always "425-555-0123".

The first task accomplished by the TransferContactToDevice function is to prompt the user to enter an object identifier for the parent object on the device (under which the content will be transferred).

HRESULT                             hr = S_OK;
WCHAR                               szSelection[81]        = {0};
CComPtr<IPortableDeviceValues>      pFinalObjectProperties;
CComPtr<IPortableDeviceContent>     pContent;

// Prompt user to enter an object identifier for the parent object on the device to transfer.
printf("Enter the identifer of the parent object which the contact will be transferred under.\n>");
hr = StringCbGetsW(szSelection,sizeof(szSelection));
if (FAILED(hr))
{
    printf("An invalid object identifier was specified, aborting content transfer\n");
}

The next step is the retrieval of contact properties, which will be used when the sample writes the new contact to the device. The retrieval of contact properties is performed by the GetRequiredPropertiesForPropertiesOnlyContact helper function.

// 2) Get the properties that describe the object being created on the device

if (SUCCEEDED(hr))
{
    hr = GetRequiredPropertiesForPropertiesOnlyContact(szSelection,              // Parent to transfer the data under
                                                       &pFinalObjectProperties);  // Returned properties describing the data
    if (FAILED(hr))
    {
        printf("! Failed to get required properties needed to transfer an image file to the device, hr = 0x%lx\n", hr);
    }
}

This function writes the following data to an IPortableDeviceValues object.

• The object identifier for the contact's parent on the device. (This is the destination where the device will store the object.)
• The object type (a contact).
• The contact name (a hard coded string of "John Kane").
• The contact phone number (a hard-coded string of "425-555-0123").

The final step creates the properties-only object on the device (using the properties set by the GetRequiredPropertiesForPropertiesOnlyContact helper function). This is accomplished by calling the IPortableDeviceContent::CreateObjectWithPropertiesOnly method.

if (SUCCEEDED(hr))
{
    PWSTR pszNewlyCreatedObject = NULL;
    hr = pContent->CreateObjectWithPropertiesOnly(pFinalObjectProperties,    // Properties describing the object data
                                                  &pszNewlyCreatedObject);
    if (SUCCEEDED(hr))
    {
        printf("The contact was transferred to the device.\nThe newly created object's ID is '%ws'\n",pszNewlyCreatedObject);
    }

    if (FAILED(hr))
    {
        printf("! Failed to transfer contact object to the device, hr = 0x%lx\n",hr);
    }

    // Free the object identifier string returned from CreateObjectWithPropertiesOnly
    CoTaskMemFree(pszNewlyCreatedObject);
    pszNewlyCreatedObject = NULL;
}

Related topics

IPortableDevice Interface

IPortableDeviceContent Interface

IPortableDeviceValues Interface

Programming Guide