Mydrmspace.com - The First Open Digital Watermarking Platform

MDSApi v0.4 documentation

MDSApi class is a client for mydrmspace.com API. Class is written in PHP5 and uses curl and SimpleXML libraries.

__construct

__construct(string $user, string $password, string $serviceName, string $serviceKey)
or
__construct(string $token, string $token_secret)

$user: User name
$password: User password
$serviceName: Service login
$serviceKey: Service password
$token: OAuth access token string
$token_secret: OAuth access token secret string

Calling constructor will result in reference to MDSApi instance or will throw exception in case of error. Constructor can be called two ways: with plain authorization data or with OAuth authorization. This class does not provide OAuth client.

sign() - Signing

sign(string $file, int $coder, array $metadata [, string $url = ''[, bool $additionalWatermark = 0]])

$file: Path to file. Can be empty if $url is set.
$coder: Coder number
$metadata: Associative array with metadata. If array is empty, metadata will not be stored. At least one element with name from the list must be defined to store metadata. Elements names: 'hlt', 'creator', 'title', 'contributor', 'description', 'coverage', 'date', 'format', 'identifier', 'language', 'publisher', 'relation', 'rights', 'source', 'subject', 'type', 'userdef1', 'userdef2', 'userdef3', 'genre'. Additionaly you can define fields with names ended with "pub" word (example: 'subjectpub', 'titlepub'). 'True' value stored in these fields will set correspondent field to be public. Otherwise field will be private. The 'hlt' field is always public. You can also define user fields names (for 'userdef1' etc.), just define fields 'userdef1name', 'userdef2name' and 'userdef3name'.; There is also possibility to enable/disable comments assigned to signed file. To do this, $metadata must have element 'comment' with value 0 or 1. If not specified, comments will be enabled.
$url: Optional URL to multimedia file to sign. If $file is empty and $url is set, the material will be downloaded.
$additionalWatermark: Optional flag that switches on/off additional (visible or audible) watermark in sound/picture (if available).

This method returns queued task number or throws an exception in case of error.

read() - Decoding

read(string $file, int $coder [, string $url])

$file: Path to file, can be empty if $url is set.
$coder: Coder number
$url: Optional, URL to the media you are reading. Will be downloaded only if $file is empty.

This method returns queued task number or throws an exception in case of error.

check() - Task status checking

check(int $task)

$task: Task number (returned by read() or sign())

If task is still being proceeded method will return task number. If task is done method returns array with public metadata (array build as in sign()). If readed file is not signed array will be empty, otherwise there are at least 'id' and 'timestamp' fields defined.

download() - downloading file

download(int $id, string $fileName)

$id: File identifier (returned as id in metadata)
$fileName: Path to file to be written

Method returns logic value if file was downloaded and is not zero bytes long.

listFiles() - listing files available to download

listFiles()

This function returns array with IDs of files which you can download() or delete().

delete() - Removing files

delete(int $id)

$id: File identifier (returned as id in metadata)

Method returns logic value if file was deleted.

coders() - Information about coders and signatures to use

coders()

This function returns array with information about coders and signatures to use. This array has a simple structure:

[coderID] => array(
		'type' => coder type (audio or picture),
		'available' => available signatures to use
		)

countComments() - counting comments

$id: File identifier (returned as id in metadata)

countComments(int $id)

This function returns number of comments of given file.

getComments() - getting comments

getComments(int $id [, int $from=0 [, int $limit=100]])

$id: File identifier (returned as id in metadata)
$from
: Indicates position of first comment to return
$limit: Indicates number of comments to return (max. 100)

This method returns associative array as given below:

Array
(
    [0] => Array
        (
            [id] => 503
            [time] => 2009-10-25 12:47:02
            [user] => testuser
            [service] => test
            [externalUser] => Joe
            [comment] => Cool photo!
        )

    [1] => Array
        (
            [id] => 502
            [time] => 2009-10-25 12:47:01
            [user] => testuser
            [service] => test
            [externalUser] => Henry
            [comment] => Sweet!
        )
)

addComment() - publishing comment

addComment(int $id, string $comment [, string $externalUser = ''])

$id: File identifier (returned as id in metadata)
$comment: Text to publish
$externalUser: User's login in external service

This method returns true or throws exception in case of error.

bye() - Logout

bye()

Changelog

0.2:

added $additionalWatermark in sign()
added possibility to enable/disable comments in sign()
new method: coders()
new method: listFiles()

0.3:

new field in $metadata array - hlt
changed sequence in sign() parameters - new parameter $url, $file can be empty
changed behaviour in read()'s $url - $file can be empty

0.4:

added OAuth authorization

mydrmspace.com - open digital watermarking platform - your creation is where your data is