README.upgrading for Widevine CDM Partner Kit v2.1
Date: 7/10/2014

This document provides details on important changes between versions of the
Widevine CDM.  Some upgrades require you to make changes to your application,
so please read carefully.

NOTE: All gyp variables have default values in platforms/global_config.gypi.
You may override these defaults in your platform-specific gypi.


New in v2.1.6:
=====
The following methods have been removed from the CDM interface (class
ContentDecryptionModule):
  * CancelKeyRequest

The following methods have been added to the CDM interface (class
ContentDecryptionModule):
  * CloseSession

Previous versions of the CDM did not dispatch key errors (Host::SendKeyError)
on failure.  This has been fixed.  If you added workarounds to your Host,
please remove them to avoid duplicate key errors.


New in v2.1.5:
=====
New gyp variables have been introduced to make the build more configurable:
  * protobuf_lib_type and protobuf_lib
    These, along with 'protoc_dir', form a new protobuf configuration model
    and replace the variables 'protobuf_source_dir', 'use_system_protobuf',
    and 'protobuf_gyp'.  For details, see platforms/global_config.gypi.


New in v2.1.3:
=====
New gyp variables have been introduced to make the build more configurable:
  * oemcrypto_v8
    The current version of OEMCrypto is v9.  Set to 'true' if your system
    supplies OEMCrypto v8.  Defaults to 'false'.

The CDM interface (class ContentDecryptionModule) has been simplified.
The following methods have been removed:
  * InitializeAudioDecoder
  * InitializeVideoDecoder
  * DeinitializeDecoder
  * ResetDecoder
  * DecryptAndDecodeFrame
  * DecryptAndDecodeSamples

The Host interface (class Host) has been simplified.
The following methods have been removed:
  * GetPrivateData
  * PersistPlatformString
  * GetPlatformByteArray
  * SetPlatformByteArray
  * PersistPlatformByteArray

The following Host methods have changed:
  * GetPlatformString
    Now does the job of GetPlatformByteArray as well.
  * SetPlatformString
    Now does the job of SetPlatformByteArray, PersistPlatformString, and
    PersistPlatformByteArray as well.
  * SetTimer
    This should schedule a single callback, not a repeating timer.  Multiple
    timer callbacks may be scheduled by the CDM at once.  All callbacks should
    occur serially on the same thread/queue as all other calls into the CDM.


New in v2.1.2:
=====
The following file locations have changed:

  ./cdm/cdm_api_internal.gyp => ./cdm/cdm.gyp
  ./cdm/cdm_api_external.gyp => ./cdm/cdm_unittests.gyp

If you have your own gyp files which depend on CDM targets, please update them
accordingly.

./build.py will use the ninja build tool if available.  Otherwise, it will
continue to use make.

The Host is no longer expected to allocate a Buffer before calling
ContentDecryptionModule::Decrypt.  The CDM will now call Host::Allocate and
DecryptedBlock::SetBuffer as needed in its Decrypt method.  To avoid the
potential for a memory leak, make sure that your Host implementation no
longer allocates a Buffer before calling Decrypt.

For more details on the Host interface, see "Widevine Security Integration
Guide for CENC: EME Supplement".


New in v2.1.1:
=====
The following file locations have changed:

  ./build/build.py => ./build.py
  ./build/platforms/ => ./platforms/
  ./build/global_config.gypi => ./platforms/global_config.gypi
  ./build/protoc.gypi => ./third_party/protoc.gypi

The file ./build/platforms/cdm_platforms.py no longer exists.  Platform
definitions are now based on the folder structure in ./platforms rather than
a python-based config file.

The OEMCrypto interface has been updated to v9, and documentation has been
updated in oemcrypto/include.  The following functions were added:

  * OEMCrypto_GetHDCPCapability
  * OEMCrypto_SupportsUsageTable
  * OEMCrypto_UpdateUsageTable
  * OEMCrypto_DeactivateUsageEntry
  * OEMCrypto_ReportUsage
  * OEMCrypto_DeleteUsageEntry
  * OEMCrypto_DeleteUsageTable

The file ./platforms/x86-64/x86-64.gypi now contains examples of how settings
can be customized for a given platform.