Line data    Source code

       1             : /*
       2             : * Copyright 2013, Mozilla Foundation and contributors
       3             : *
       4             : * Licensed under the Apache License, Version 2.0 (the "License");
       5             : * you may not use this file except in compliance with the License.
       6             : * You may obtain a copy of the License at
       7             : *
       8             : * http://www.apache.org/licenses/LICENSE-2.0
       9             : *
      10             : * Unless required by applicable law or agreed to in writing, software
      11             : * distributed under the License is distributed on an "AS IS" BASIS,
      12             : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      13             : * See the License for the specific language governing permissions and
      14             : * limitations under the License.
      15             : */
      16             : 
      17             : #ifndef GMP_STORAGE_h_
      18             : #define GMP_STORAGE_h_
      19             : 
      20             : #include "gmp-errors.h"
      21             : #include <stdint.h>
      22             : 
      23             : // Maximum size of a record, in bytes; 10 megabytes.
      24             : #define GMP_MAX_RECORD_SIZE (10 * 1024 * 1024)
      25             : 
      26             : // Maximum length of a record name in bytes.
      27             : #define GMP_MAX_RECORD_NAME_SIZE 2000
      28             : 
      29             : // Provides basic per-origin storage for CDMs. GMPRecord instances can be
      30             : // retrieved by calling GMPPlatformAPI->openstorage. Multiple GMPRecords
      31             : // with different names can be open at once, but a single record can only
      32             : // be opened by one client at a time. This interface is asynchronous, with
      33             : // results being returned via callbacks to the GMPRecordClient pointer
      34             : // provided to the GMPPlatformAPI->openstorage call, on the main thread.
      35             : //
      36             : // Lifecycle: Once opened, the GMPRecord object remains allocated until
      37             : // GMPRecord::Close() is called. If any GMPRecord function, either
      38             : // synchronously or asynchronously through a GMPRecordClient callback,
      39             : // returns an error, the GMP is responsible for calling Close() on the
      40             : // GMPRecord to delete the GMPRecord object's memory. If your GMP does not
      41             : // call Close(), the GMPRecord's memory will leak.
      42           0 : class GMPRecord {
      43             : public:
      44             : 
      45             :   // Opens the record. Calls OpenComplete() once the record is open.
      46             :   // Note: Only work when GMP is loading content from a webserver.
      47             :   // Does not work for web pages on loaded from disk.
      48             :   // Note: OpenComplete() is only called if this returns GMPNoErr.
      49             :   virtual GMPErr Open() = 0;
      50             : 
      51             :   // Reads the entire contents of the record, and calls
      52             :   // GMPRecordClient::ReadComplete() once the operation is complete.
      53             :   // Note: ReadComplete() is only called if this returns GMPNoErr.
      54             :   virtual GMPErr Read() = 0;
      55             : 
      56             :   // Writes aDataSize bytes of aData into the record, overwriting the
      57             :   // contents of the record, truncating it to aDataSize length.
      58             :   // Overwriting with 0 bytes "deletes" the record.
      59             :   // Note: WriteComplete is only called if this returns GMPNoErr.
      60             :   virtual GMPErr Write(const uint8_t* aData, uint32_t aDataSize) = 0;
      61             : 
      62             :   // Closes a record, deletes the GMPRecord object. The GMPRecord object
      63             :   // must not be used after this is called, request a new one with
      64             :   // GMPPlatformAPI->openstorage to re-open this record. Cancels all
      65             :   // callbacks.
      66             :   virtual GMPErr Close() = 0;
      67             : 
      68           0 :   virtual ~GMPRecord() {}
      69             : };
      70             : 
      71             : // Callback object that receives the results of GMPRecord calls. Callbacks
      72             : // run asynchronously to the GMPRecord call, on the main thread.
      73           0 : class GMPRecordClient {
      74             :  public:
      75             : 
      76             :   // Response to a GMPRecord::Open() call with the open |status|.
      77             :   // aStatus values:
      78             :   // - GMPNoErr - Record opened successfully. Record may be empty.
      79             :   // - GMPRecordInUse - This record is in use by another client.
      80             :   // - GMPGenericErr - Unspecified error.
      81             :   // If aStatus is not GMPNoErr, the GMPRecord is unusable, and you must
      82             :   // call Close() on the GMPRecord to dispose of it.
      83             :   virtual void OpenComplete(GMPErr aStatus) = 0;
      84             : 
      85             :   // Response to a GMPRecord::Read() call, where aData is the record contents,
      86             :   // of length aDataSize.
      87             :   // aData is only valid for the duration of the call to ReadComplete.
      88             :   // Copy it if you want to hang onto it!
      89             :   // aStatus values:
      90             :   // - GMPNoErr - Record contents read successfully, aDataSize 0 means record
      91             :   //   is empty.
      92             :   // - GMPRecordInUse - There are other operations or clients in use on
      93             :   //   this record.
      94             :   // - GMPGenericErr - Unspecified error.
      95             :   // If aStatus is not GMPNoErr, the GMPRecord is unusable, and you must
      96             :   // call Close() on the GMPRecord to dispose of it.
      97             :   virtual void ReadComplete(GMPErr aStatus,
      98             :                             const uint8_t* aData,
      99             :                             uint32_t aDataSize) = 0;
     100             : 
     101             :   // Response to a GMPRecord::Write() call.
     102             :   // - GMPNoErr - File contents written successfully.
     103             :   // - GMPRecordInUse - There are other operations or clients in use on
     104             :   //   this record.
     105             :   // - GMPGenericErr - Unspecified error.
     106             :   // If aStatus is not GMPNoErr, the GMPRecord is unusable, and you must
     107             :   // call Close() on the GMPRecord to dispose of it.
     108             :   virtual void WriteComplete(GMPErr aStatus) = 0;
     109             : 
     110           0 :   virtual ~GMPRecordClient() {}
     111             : };
     112             : 
     113             : #endif // GMP_STORAGE_h_