IWMDMStorage::GetRights

The GetRights method retrieves the rights information for an object.

Syntax

HRESULT GetRights(
  PWMDMRIGHTS*  ppRights,
  UINT*  pnRightsCount,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

ppRights

[out]  Pointer to an array of WMDMRIGHTS structures that contain the storage object rights information. This parameter is included in the output message authentication code.

pnRightsCount

[out]  Pointer to the number of WMDMRIGHTS structures in the ppRights array. This parameter is included in the output message authentication code.

abMac

[in, out]  Array of eight bytes containing the message authentication code (MAC) for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

The method returns an HRESULT. All the interface methods in Windows Media Device Manager and service provider can return any of the following classes of error codes:

• Standard COM error codes
• Windows error codes converted to HRESULT values
• Windows Media Device Manager error codes

For a complete list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code	Description
S_OK	The method succeeded.
E_INVALIDARG	The ppRights or pnRightsCount parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED	Rights are not supported for this object.
E_FAIL	An unspecified error occurred.
WMDM_E_NOTCERTIFIED	The caller is not certified.
WMDM_E_MAC_CHECK_FAILED	The message authentication check failed.

Remarks

Object rights describe the usage permissions for digital media content. For example, the WMDMRIGHTS structure can contain information concerning how many times a file can be played and who can play it.

The ppRights array is allocated by this method, and must be freed by the application using CoTaskMemFree, a standard Win32 function.

After calling this method, an application can calculate the message authentication code (MAC) values of parameters and compare them with output MAC values to ensure that the parameters have not been tampered with. The following example code shows one way to do this

Example Code

CSecureChannelClient  *pSCClient;
IWMDMStorage  *pStorgae;

HMAC  hMAC;
BYTE  abMAC[WMDM_MAC_LENGTH];
BYTE  abMACVerify[WMDM_MAC_LENGTH];

// pSCClient and pStorage creation code that is shipped
//                    with Windows Media Device Manager

hr = pStorage->GetRights(&pRights, &nRightsCount, abMAC);
if ( SUCCEEDED(hr))
{
    pSCClient->MACInit(&hMAC);
    pSCClient->MACUpdate(hMAC, (BYTE*)(pRights), 
                    sizeof(WMDMRIGHTS) * nRightsCount);
    pSCClient->MACUpdate(hMAC, (BYTE*)(&nRightsCount), 
                                 sizeof(nRightsCount));
    pSCClient->MACFinal(hMAC, (BYTE*)abMACVerify);
    if (memcmp(abMACVerify, abMAC, sizeof(abMAC)) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
    }
}

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

• IWMDMStorage Interface
• WMDMRIGHTS