tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

gmp-storage.h (4701B)

      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 <stdint.h>
     21 
     22 #include "gmp-errors.h"
     23 
     24 // Maximum size of a record, in bytes; 10 megabytes.
     25 #define GMP_MAX_RECORD_SIZE (10 * 1024 * 1024)
     26 
     27 // Maximum length of a record name in bytes.
     28 #define GMP_MAX_RECORD_NAME_SIZE 2000
     29 
     30 // Provides basic per-origin storage for CDMs. GMPRecord instances can be
     31 // retrieved by calling GMPPlatformAPI->openstorage. Multiple GMPRecords
     32 // with different names can be open at once, but a single record can only
     33 // be opened by one client at a time. This interface is asynchronous, with
     34 // results being returned via callbacks to the GMPRecordClient pointer
     35 // provided to the GMPPlatformAPI->openstorage call, on the main thread.
     36 //
     37 // Lifecycle: Once opened, the GMPRecord object remains allocated until
     38 // GMPRecord::Close() is called. If any GMPRecord function, either
     39 // synchronously or asynchronously through a GMPRecordClient callback,
     40 // returns an error, the GMP is responsible for calling Close() on the
     41 // GMPRecord to delete the GMPRecord object's memory. If your GMP does not
     42 // call Close(), the GMPRecord's memory will leak.
     43 class GMPRecord {
     44 public:
     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  virtual ~GMPRecord() = default;
     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 class GMPRecordClient {
     74 public:
     75  // Response to a GMPRecord::Open() call with the open |status|.
     76  // aStatus values:
     77  // - GMPNoErr - Record opened successfully. Record may be empty.
     78  // - GMPRecordInUse - This record is in use by another client.
     79  // - GMPGenericErr - Unspecified error.
     80  // If aStatus is not GMPNoErr, the GMPRecord is unusable, and you must
     81  // call Close() on the GMPRecord to dispose of it.
     82  virtual void OpenComplete(GMPErr aStatus) = 0;
     83 
     84  // Response to a GMPRecord::Read() call, where aData is the record contents,
     85  // of length aDataSize.
     86  // aData is only valid for the duration of the call to ReadComplete.
     87  // Copy it if you want to hang onto it!
     88  // aStatus values:
     89  // - GMPNoErr - Record contents read successfully, aDataSize 0 means record
     90  //   is empty.
     91  // - GMPRecordInUse - There are other operations or clients in use on
     92  //   this record.
     93  // - GMPGenericErr - Unspecified error.
     94  // If aStatus is not GMPNoErr, the GMPRecord is unusable, and you must
     95  // call Close() on the GMPRecord to dispose of it.
     96  virtual void ReadComplete(GMPErr aStatus, const uint8_t* aData,
     97                            uint32_t aDataSize) = 0;
     98 
     99  // Response to a GMPRecord::Write() call.
    100  // - GMPNoErr - File contents written successfully.
    101  // - GMPRecordInUse - There are other operations or clients in use on
    102  //   this record.
    103  // - GMPGenericErr - Unspecified error.
    104  // If aStatus is not GMPNoErr, the GMPRecord is unusable, and you must
    105  // call Close() on the GMPRecord to dispose of it.
    106  virtual void WriteComplete(GMPErr aStatus) = 0;
    107 
    108  virtual ~GMPRecordClient() = default;
    109 };
    110 
    111 #endif  // GMP_STORAGE_h_