Strings Property

Article
09/21/2010

The String property gets a ISoftUSBStrings object that holds a collection of ISoftUSBString objects that represent a device's string descriptors.

This property is read-only.

Syntax

HRESULT get_Strings(
  [out, retval]  ISoftUSBStrings **ppiStringList
);

Property Value

Caller-allocated space to hold a pointer to the ISoftUSBStrings object that holds a collection of strings that are associated with the device.

Error Codes

Strings returns S_OK if the operation succeeds or E_POINTER if the ppiStringList parameter is not a valid pointer.

Remarks

The string descriptor index that you specify within other descriptors (for example, ISoftUSBDevice::Manufacturer) determines the index of the corresponding ISoftUSBString object in the collection that the Strings property retrieves.

The following C++ code example shows how to get the Strings property.

HRESULT CLoopBackDevice::CreateStrings()
{
    HRESULT             hr = S_OK;
 ISoftUSBStrings *piStringList = NULL;
 ISoftUSBString     *piStringManufacturer = NULL;
    BSTR                bstrManufacturer = ::SysAllocString(L"Microsoft Corporation");
    VARIANT             varIndex; VariantInit(&varIndex);

    // Check that all BSTR allocations succeeded
 if(0 != ::SysStringLen(bstrManufacturer)
    {
 hr =  E_OUTOFMEMORY;
 goto Exit;
    }

    //Set up the variant that is used as the index
 varIndex.vt = VT_I4;
 varIndex.lVal = STRING_IDX_MANUFACTURER;

    // Create and initialize the string descriptors. Also create a string 
    // descriptor index for each. This index is used both to set the string's
    // descriptor position in m_piUSBDevice.Strings and is the index value 
    // that GetDescriptors request from the host. Do not use 
    // string descriptor index zero because that value is a reserved value for a 
    // device's language ID descriptor.

    // Get the string list from the device
 hr = m_piUSBDevice->get_Strings(&piStringList);
 if(FAILED(hr))
 goto Exit;

 hr = CoCreateInstance(CLSID_SoftUSBString,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          __uuidof(ISoftUSBString),     
 reinterpret_cast<void**>(&piStringManufacturer));
 if(FAILED(hr))
 goto Exit;

 hr = piStringManufacturer->put_Value(bstrManufacturer);
 if(FAILED(hr))
 goto Exit;
 
 hr = piStringList->Add(reinterpret_cast<SoftUSBString*>(piStringManufacturer), varIndex);
 if(FAILED(hr))
 goto Exit;
 
Exit:
 
 if (NULL != piStringList)
 piStringList->Release();
 if (NULL != piStringManufacturer)
 piStringManufacturer->Release();

    ::SysFreeString(bstrManufacturer);
 return hr;
}

Requirements

Header

SoftUSBif.h

Share via