flash.net.drm

# DRMManager - AS3

Package | flash.net.drm
Class | public class DRMManager
Inheritance | DRMManager EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

The DRMManager manages the retrieval and storage of the vouchers needed to view DRM-protected content. With the static `DRMManager.getDRMManager()` method, you can access the existing DRMManager object to perform the following DRM-management tasks:

- Preload vouchers from a media rights server, using a DRMContentData object.
- Query the local cache for an individual voucher, using a DRMContentData object.
- Reset all vouchers (AIR only)

No method is provided for enumerating all the vouchers in the local cache.

Do not create an instance of the DRMManager class. Use the static `DRMManager.getDRMManager()` to access the existing DRMManager object.

AIR profile support: This feature is supported on all desktop operating systems and AIR for TV devices, but it is not supported on mobile devices. You can test for support at run time using the `DRMManager.isSupported` property. See AIR Profile Support for more information regarding API support across multiple profiles.

Learn more

Using digital rights management

Related API Elements

flash.net.NetStream
flash.net.drm.DRMVoucher
flash.net.drm.DRMContentData

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | isSupported : Boolean [static] [read-only] The isSupported property is set to true if the DRMManager class is supported on the current platform, otherwise it is set to false. | DRMManager
|  | networkIdleTimeout : Number [static] | DRMManager

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | addToDeviceGroup(deviceGroup:DRMDeviceGroup, forceRefresh:Boolean = false):void adds the currently running device to a device group. | DRMManager
|  | authenticate(serverURL:String, domain:String, username:String, password:String):void Authenticates a user. | DRMManager
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | getDRMManager():DRMManager [static] Returns an instance of the singleton DRMManager object. | DRMManager
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | loadPreviewVoucher(contentData:DRMContentData):void Gets a preview voucher from the license server, which you can use to let a user verify that they can play content on particular computer. | DRMManager
|  | loadVoucher(contentData:DRMContentData, setting:String):void Loads a voucher from a media rights server or the local voucher cache. | DRMManager
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | removeFromDeviceGroup(deviceGroup:DRMDeviceGroup):void Removes the currently running device from a device group. | DRMManager
|  | resetDRMVouchers():void In AIR applications this deletes all locally cached digital rights management (DRM) voucher data. | DRMManager
|  | returnVoucher(inServerURL:String, immediateCommit:Boolean, licenseID:String, policyID:String):void Returns to the license server all vouchers that match all specified criteria. | DRMManager
|  | setAuthenticationToken(serverUrl:String, domain:String, token:ByteArray):void Sets the authentication token to use for communication with the specified server and domain. | DRMManager
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | storeVoucher(voucher:ByteArray):void | DRMManager
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | authenticationComplete | The DRMManager dispatches a DRMAuthenticationCompleteEvent object when the user is authenticated by the media rights server after a call to the authenticate() method. | DRMManager
|  | authenticationError | The DRMManager dispatches a DRMAuthenticationErrorEvent object when the user is not authenticated by the media rights server after a call to the authenticate() method. | DRMManager
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | drmError | The DRMManager dispatches a DRMErrorEvent object when a requested voucher cannot be obtained from the media rights server. | DRMManager
|  | drmStatus | The DRMManager dispatches a DRMStatusEvent object when a requested voucher is obtained from the media rights server. | DRMManager

Property Detail

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 10.1, AIR 2

The `isSupported` property is set to `true` if the DRMManager class is supported on the current platform, otherwise it is set to `false`.

Implementation
`public static function get isSupported():Boolean`

### networkIdleTimeout

property

`networkIdleTimeout:Number`

Implementation
`public static function get networkIdleTimeout():Number`
`public static function set networkIdleTimeout(value:Number):void`
Method Detail

### addToDeviceGroup

()
method

`public function addToDeviceGroup(deviceGroup:DRMDeviceGroup, forceRefresh:Boolean = false):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.0, Flash Player 11.9

adds the currently running device to a device group.

Parameters

| `deviceGroup:DRMDeviceGroup`
| `forceRefresh:Boolean` (default = `false`)``

### authenticate

()
method

`public function authenticate(serverURL:String, domain:String, username:String, password:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

Authenticates a user.

Listen for the `authenticationComplete` and `authenticationError` events to determine the outcome of the authentication attempt. Multiple `authenticate()` calls are queued. The AuthenticationCompleteEvent object dispatched for the `authenticationComplete` event contains contains an authentication token that your application can save.

You can use a saved authentication token, or a token downloaded by another means, to establish an authenticated session with the media rights server in the future. To establish a session using a token, call the DRMManager `setAuthenticationToken()` method. The properties of the token, such as expiration date, are determined by the settings of the server that generates the token.

Important (AIR only): The `authenticate()` method will not succeed when a user's Internet connection passes through a proxy server requiring authentication. Although such users are not able to preload a DRM voucher that requires authentication, your application can obtain the voucher by beginning playback and using the NetStream `setAuthenticationCredentials()` method to log the user into both the proxy and the media rights servers. Once the voucher has been obtained, the user can view the content offline (as long as the license represented by the voucher allows offline playback).

Parameters

| `serverURL:String` — The URL of a media rights server that can provide a voucher for viewing protected content
| `domain:String` — A domain on the server (not a network or Internet domain name)
| `username:String` — The user name
| `password:String` — The user password

Related API Elements

flash.net.NetStream.setAuthenticationCredentials()
setAuthenticationToken()

### getDRMManager

()
method

`public static function getDRMManager():DRMManager`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

Returns an instance of the singleton DRMManager object.

One DRMManager instance exists for each security domain.

Returns

| `DRMManager`

Related API Elements

flash.system.SecurityDomain

### loadPreviewVoucher

()
method

`public function loadPreviewVoucher(contentData:DRMContentData):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Player 10.1

Gets a preview voucher from the license server, which you can use to let a user verify that they can play content on particular computer. This capability lets users verify that they can play content on their computer before buying and downloading the content. It is useful when the user's computer doesn't have the necessary output protection capabilities or necessary software to play content.

Like `loadVoucher()`, this method is an asynchronous call and issues a DRMStatusEvent on completion or a DRMErrorEvent in case of errors.

Parameters

| `contentData:DRMContentData`

### loadVoucher

()
method

`public function loadVoucher(contentData:DRMContentData, setting:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

Loads a voucher from a media rights server or the local voucher cache.

The voucher is loaded according to the `setting` parameter:

- LoadVoucherSetting.FORCE_REFRESH: The voucher is always downloaded from the media rights server.
- LoadVoucherSetting.LOCAL_ONLY: The voucher is only loaded from the local cache.
- LoadVoucherSetting.ALLOW_SERVER: The voucher is loaded from the local cache, if possible, but otherwise is downloaded from the server.

The LoadVoucherSetting class defines string constants to use as values for the `setting` parameter.

When the voucher is successfully loaded, the DRMManager dispatches a DRM status event. Your application can begin playback as soon as the voucher is loaded. The loaded voucher is available in the `voucher` property of the dispatched DRMStatusEvent object. You can use this voucher object to display the associated media rights information to the user.

If a voucher cannot be loaded from the media rights server, a DRM error event is dispatched. The `errorID` property of the dispatched DRMErrorEvent object indicates the reason for the failure. Common causes of failure include attempting to connect to the media rights server when the user is offline and attempting to load a voucher when the user is not logged in. Your application can respond to these errors and take corrective action. For example, if authentication credentials are required to download the voucher, you can prompt the user for their account user name and password, call the DRMManager `authenticate()` method, and then attempt to load the voucher again.

If a voucher cannot be obtained from the local cache and the `localOnly` setting is used, a DRMErrorEvent is not dispatched. Instead, a DRM status event is dispatched. The `detail` property of this DRMStatusEvent object is still `DRM.voucherObtained`, but the `voucher` property is `null`.

Parameters

| `contentData:DRMContentData` — The DRMContentData object from a DRM-protected media file
| `setting:String` — Determines whether the voucher is retrieved from the local cache or the media rights server

### removeFromDeviceGroup

()
method

`public function removeFromDeviceGroup(deviceGroup:DRMDeviceGroup):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.0, Flash Player 11.9

Removes the currently running device from a device group.

Parameters

| `deviceGroup:DRMDeviceGroup`

### resetDRMVouchers

()
method

`public function resetDRMVouchers():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 11.8

In AIR applications this deletes all locally cached digital rights management (DRM) voucher data. For browser based applications this is only available during 3322, 3346, 3323, 3326 errors, and behaves like the Protected Content Playback Settings panel.

The application must download the required vouchers again for the user to be able to access encrypted content. Calling this function is equivalent to calling `Netstream.resetDRMVouchers()`.

Throws

| `IOError` — The voucher data cannot be deleted.

Related API Elements

flash.net.NetStream.resetDRMVouchers()

### returnVoucher

()
method

`public function returnVoucher(inServerURL:String, immediateCommit:Boolean, licenseID:String, policyID:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.8, AIR 3.8

Returns to the license server all vouchers that match all specified criteria. When a voucher is returned, it is removed from on disk storage and from memory. This will not interrupt Netstreams and AVStreams that are currently using the returned vouchers for video playback, but will prohibit future playback. DRMManager will issue a DRMReturnVoucherCompleteEvent on success or a DRMReturnVoucherErrorEvent on error. Will throw an ArgumentError if inServerURL is null or if licenseID and policyID are both null.

Parameters

| `inServerURL:String` — The license server URLs from which the returned licenses were downloaded.
| `immediateCommit:Boolean` — Reserved. The only supported value is true.
| `licenseID:String` — (optional) Vouchers matching this licenseID will be returned. If null, policyID will be used instead.
| `policyID:String` — (optional) Vouchers matching this policyID will be returned. If null, licenseID will be used instead. If both licenseID and policyID are non-null, only a voucher that matches both licenseID and policyID will be returned.

### setAuthenticationToken

()
method

`public function setAuthenticationToken(serverUrl:String, domain:String, token:ByteArray):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

Sets the authentication token to use for communication with the specified server and domain.

Authentication tokens are available from the `token` property of the DRMAuthenticationCompleteEvent object dispatched after a successful call to the `authenticate()` method. The token is cached automatically for the session, but you can use the `setAuthenticationToken()` method to manage tokens directly.

Setting a token overwrites any existing cached token for the server and domain. Set the `token` parameter to `null` to clear the cached token.

Parameters

| `serverUrl:String` — The URL of the media rights server
| `domain:String` — The DRMContentData
| `token:ByteArray` — The authentication token

### storeVoucher

()
method

`public function storeVoucher(voucher:ByteArray):void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.0, AIR 3.0

Parameters

| `voucher:ByteArray`

Event Detail

### authenticationComplete

Event

Event Object Type: `flash.events.DRMAuthenticationCompleteEvent`
property DRMAuthenticationCompleteEvent.type = `flash.events.DRMAuthenticationCompleteEvent.AUTHENTICATION_COMPLETE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

The DRMManager dispatches a DRMAuthenticationCompleteEvent object when the user is authenticated by the media rights server after a call to the `authenticate()` method.

The string constant to use for the authentication complete event in the type parameter when adding and removing event listeners.

### authenticationError

Event

Event Object Type: `flash.events.DRMAuthenticationErrorEvent`
property DRMAuthenticationErrorEvent.type = `flash.events.DRMAuthenticationErrorEvent.AUTHENTICATION_ERROR`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

The DRMManager dispatches a DRMAuthenticationErrorEvent object when the user is not authenticated by the media rights server after a call to the `authenticate()` method.

The string constant to use for the authentication error event in the type parameter when adding and removing event listeners.

### drmError

Event

Event Object Type: `flash.events.DRMErrorEvent`
property DRMErrorEvent.type = `flash.events.DRMErrorEvent.DRM_ERROR`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

The DRMManager dispatches a DRMErrorEvent object when a requested voucher cannot be obtained from the media rights server.

Note: When an attempt to load a voucher from the local voucher cache (using the `localOnly` as the `source` parameter) fails, a DRMErrorEvent object is not dispatched. Instead, a DRMStatusEvent object with a `voucher` property set to `null` is dispatched.

The `DRMErrorEvent.DRM_ERROR` constant defines the value of the `type` property of a `drmError` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`errorID` | A numerical error code assigned to the problem.
`subErrorID` | An error code that indicates more detailed information about the underlying problem.
`target` | The NetStream object.

### drmStatus

Event

Event Object Type: `flash.events.DRMStatusEvent`
property DRMStatusEvent.type = `flash.events.DRMStatusEvent.DRM_STATUS`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5, Flash Player 10.1

The DRMManager dispatches a DRMStatusEvent object when a requested voucher is obtained from the media rights server.

The `DRMStatusEvent.DRM_STATUS` constant defines the value of the `type` property of a `drmStatus` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`detail` | A string explaining the context of the status event.
`isAnonymous` | Indicates whether the content protected with DRM encryption is available without requiring a user to provide authentication credentials.
`isAvailableOffline` | Indicates whether the content protected with DRM encryption is available offline.
`offlineLeasePeriod` | The remaining number of days that content can be viewed offline.
`policies` | A custom object of the DRM status event.
`target` | The NetStream object.
`voucherEndDate` | The absolute date on which the voucher expires and the content can no longer be viewed by users
`contentData` | The DRMContentData for the content
`voucher` | The DRMVoucher object for the content.
`isLocal` | Indicates whether the content is stored on the local file system

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00