Home | History | Annotate | Download | only in converter 
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      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 __FWDLOCKCONV_H__
     18 #define __FWDLOCKCONV_H__
     19 
     20 #ifdef __cplusplus
     21 extern "C" {
     22 #endif
     23 
     24 #include <sys/types.h>
     25 
     26 /**
     27  * The size of the data and header signatures combined. The signatures are adjacent to each other in
     28  * the produced output file.
     29  */
     30 #define FWD_LOCK_SIGNATURES_SIZE (2 * 20)
     31 
     32 /**
     33  * Data type for the output from FwdLockConv_ConvertData.
     34  */
     35 typedef struct FwdLockConv_ConvertData_Output {
     36     /// The converted data.
     37     void *pBuffer;
     38 
     39     /// The size of the converted data.
     40     size_t numBytes;
     41 
     42     /// The file position where the error occurred, in the case of a syntax error.
     43     off64_t errorPos;
     44 } FwdLockConv_ConvertData_Output_t;
     45 
     46 /**
     47  * Data type for the output from FwdLockConv_CloseSession.
     48  */
     49 typedef struct FwdLockConv_CloseSession_Output {
     50     /// The final set of signatures.
     51     unsigned char signatures[FWD_LOCK_SIGNATURES_SIZE];
     52 
     53     /// The offset in the produced output file where the signatures are located.
     54     off64_t fileOffset;
     55 
     56     /// The file position where the error occurred, in the case of a syntax error.
     57     off64_t errorPos;
     58 } FwdLockConv_CloseSession_Output_t;
     59 
     60 /**
     61  * Data type for the output from the conversion process.
     62  */
     63 typedef union FwdLockConv_Output {
     64     FwdLockConv_ConvertData_Output_t fromConvertData;
     65     FwdLockConv_CloseSession_Output_t fromCloseSession;
     66 } FwdLockConv_Output_t;
     67 
     68 /**
     69  * Data type for the Posix-style read function used by the converter in pull mode.
     70  *
     71  * @param[in] fileDesc The file descriptor of a file opened for reading.
     72  * @param[out] pBuffer A reference to the buffer that should receive the read data.
     73  * @param[in] numBytes The number of bytes to read.
     74  *
     75  * @return The number of bytes read.
     76  * @retval -1 Failure.
     77  */
     78 typedef ssize_t FwdLockConv_ReadFunc_t(int fileDesc, void *pBuffer, size_t numBytes);
     79 
     80 /**
     81  * Data type for the Posix-style write function used by the converter in pull mode.
     82  *
     83  * @param[in] fileDesc The file descriptor of a file opened for writing.
     84  * @param[in] pBuffer A reference to the buffer containing the data to be written.
     85  * @param[in] numBytes The number of bytes to write.
     86  *
     87  * @return The number of bytes written.
     88  * @retval -1 Failure.
     89  */
     90 typedef ssize_t FwdLockConv_WriteFunc_t(int fileDesc, const void *pBuffer, size_t numBytes);
     91 
     92 /**
     93  * Data type for the Posix-style lseek function used by the converter in pull mode.
     94  *
     95  * @param[in] fileDesc The file descriptor of a file opened for writing.
     96  * @param[in] offset The offset with which to update the file position.
     97  * @param[in] whence One of SEEK_SET, SEEK_CUR, and SEEK_END.
     98  *
     99  * @return The new file position.
    100  * @retval ((off64_t)-1) Failure.
    101  */
    102 typedef off64_t FwdLockConv_LSeekFunc_t(int fileDesc, off64_t offset, int whence);
    103 
    104 /**
    105  * The status codes returned by the converter functions.
    106  */
    107 typedef enum FwdLockConv_Status {
    108     /// The operation was successful.
    109     FwdLockConv_Status_OK = 0,
    110 
    111     /// An actual argument to the function is invalid (a program error on the caller's part).
    112     FwdLockConv_Status_InvalidArgument = 1,
    113 
    114     /// There is not enough free dynamic memory to complete the operation.
    115     FwdLockConv_Status_OutOfMemory = 2,
    116 
    117     /// An error occurred while opening the input file.
    118     FwdLockConv_Status_FileNotFound = 3,
    119 
    120     /// An error occurred while creating the output file.
    121     FwdLockConv_Status_FileCreationFailed = 4,
    122 
    123     /// An error occurred while reading from the input file.
    124     FwdLockConv_Status_FileReadError = 5,
    125 
    126     /// An error occurred while writing to the output file.
    127     FwdLockConv_Status_FileWriteError = 6,
    128 
    129     /// An error occurred while seeking to a new file position within the output file.
    130     FwdLockConv_Status_FileSeekError = 7,
    131 
    132     /// The input file is not a syntactically correct OMA DRM v1 Forward Lock file.
    133     FwdLockConv_Status_SyntaxError = 8,
    134 
    135     /// Support for this DRM file format has been disabled in the current product configuration.
    136     FwdLockConv_Status_UnsupportedFileFormat = 9,
    137 
    138     /// The content transfer encoding is not one of "binary", "base64", "7bit", or "8bit"
    139     /// (case-insensitive).
    140     FwdLockConv_Status_UnsupportedContentTransferEncoding = 10,
    141 
    142     /// The generation of a random number failed.
    143     FwdLockConv_Status_RandomNumberGenerationFailed = 11,
    144 
    145     /// Key encryption failed.
    146     FwdLockConv_Status_KeyEncryptionFailed = 12,
    147 
    148     /// The calculation of a keyed hash for integrity protection failed.
    149     FwdLockConv_Status_IntegrityProtectionFailed = 13,
    150 
    151     /// There are too many ongoing sessions for another one to be opened.
    152     FwdLockConv_Status_TooManySessions = 14,
    153 
    154     /// An unexpected error occurred.
    155     FwdLockConv_Status_ProgramError = 15
    156 } FwdLockConv_Status_t;
    157 
    158 /**
    159  * Opens a session for converting an OMA DRM v1 Forward Lock file to the internal Forward Lock file
    160  * format.
    161  *
    162  * @param[out] pSessionId The session ID.
    163  * @param[out] pOutput The output from the conversion process (initialized).
    164  *
    165  * @return A status code.
    166  * @retval FwdLockConv_Status_OK
    167  * @retval FwdLockConv_Status_InvalidArgument
    168  * @retval FwdLockConv_Status_TooManySessions
    169  */
    170 FwdLockConv_Status_t FwdLockConv_OpenSession(int *pSessionId, FwdLockConv_Output_t *pOutput);
    171 
    172 /**
    173  * Supplies the converter with data to convert. The caller is expected to write the converted data
    174  * to file. Can be called an arbitrary number of times.
    175  *
    176  * @param[in] sessionId The session ID.
    177  * @param[in] pBuffer A reference to a buffer containing the data to convert.
    178  * @param[in] numBytes The number of bytes to convert.
    179  * @param[in,out] pOutput The output from the conversion process (allocated/reallocated).
    180  *
    181  * @return A status code.
    182  * @retval FwdLockConv_Status_OK
    183  * @retval FwdLockConv_Status_InvalidArgument
    184  * @retval FwdLockConv_Status_OutOfMemory
    185  * @retval FwdLockConv_Status_SyntaxError
    186  * @retval FwdLockConv_Status_UnsupportedFileFormat
    187  * @retval FwdLockConv_Status_UnsupportedContentTransferEncoding
    188  * @retval FwdLockConv_Status_RandomNumberGenerationFailed
    189  * @retval FwdLockConv_Status_KeyEncryptionFailed
    190  * @retval FwdLockConv_Status_DataEncryptionFailed
    191  */
    192 FwdLockConv_Status_t FwdLockConv_ConvertData(int sessionId,
    193                                              const void *pBuffer,
    194                                              size_t numBytes,
    195                                              FwdLockConv_Output_t *pOutput);
    196 
    197 /**
    198  * Closes a session for converting an OMA DRM v1 Forward Lock file to the internal Forward Lock
    199  * file format. The caller must update the produced output file at the indicated file offset with
    200  * the final set of signatures.
    201  *
    202  * @param[in] sessionId The session ID.
    203  * @param[in,out] pOutput The output from the conversion process (deallocated and overwritten).
    204  *
    205  * @return A status code.
    206  * @retval FwdLockConv_Status_OK
    207  * @retval FwdLockConv_Status_InvalidArgument
    208  * @retval FwdLockConv_Status_OutOfMemory
    209  * @retval FwdLockConv_Status_IntegrityProtectionFailed
    210  */
    211 FwdLockConv_Status_t FwdLockConv_CloseSession(int sessionId, FwdLockConv_Output_t *pOutput);
    212 
    213 /**
    214  * Converts an open OMA DRM v1 Forward Lock file to the internal Forward Lock file format in pull
    215  * mode.
    216  *
    217  * @param[in] inputFileDesc The file descriptor of the open input file.
    218  * @param[in] fpReadFunc A reference to a read function that can operate on the open input file.
    219  * @param[in] outputFileDesc The file descriptor of the open output file.
    220  * @param[in] fpWriteFunc A reference to a write function that can operate on the open output file.
    221  * @param[in] fpLSeekFunc A reference to an lseek function that can operate on the open output file.
    222  * @param[out] pErrorPos
    223  *   The file position where the error occurred, in the case of a syntax error. May be NULL.
    224  *
    225  * @return A status code.
    226  * @retval FwdLockConv_Status_OK
    227  * @retval FwdLockConv_Status_InvalidArgument
    228  * @retval FwdLockConv_Status_OutOfMemory
    229  * @retval FwdLockConv_Status_FileReadError
    230  * @retval FwdLockConv_Status_FileWriteError
    231  * @retval FwdLockConv_Status_FileSeekError
    232  * @retval FwdLockConv_Status_SyntaxError
    233  * @retval FwdLockConv_Status_UnsupportedFileFormat
    234  * @retval FwdLockConv_Status_UnsupportedContentTransferEncoding
    235  * @retval FwdLockConv_Status_RandomNumberGenerationFailed
    236  * @retval FwdLockConv_Status_KeyEncryptionFailed
    237  * @retval FwdLockConv_Status_DataEncryptionFailed
    238  * @retval FwdLockConv_Status_IntegrityProtectionFailed
    239  * @retval FwdLockConv_Status_TooManySessions
    240  */
    241 FwdLockConv_Status_t FwdLockConv_ConvertOpenFile(int inputFileDesc,
    242                                                  FwdLockConv_ReadFunc_t *fpReadFunc,
    243                                                  int outputFileDesc,
    244                                                  FwdLockConv_WriteFunc_t *fpWriteFunc,
    245                                                  FwdLockConv_LSeekFunc_t *fpLSeekFunc,
    246                                                  off64_t *pErrorPos);
    247 
    248 /**
    249  * Converts an OMA DRM v1 Forward Lock file to the internal Forward Lock file format in pull mode.
    250  *
    251  * @param[in] pInputFilename A reference to the input filename.
    252  * @param[in] pOutputFilename A reference to the output filename.
    253  * @param[out] pErrorPos
    254  *   The file position where the error occurred, in the case of a syntax error. May be NULL.
    255  *
    256  * @return A status code.
    257  * @retval FwdLockConv_Status_OK
    258  * @retval FwdLockConv_Status_InvalidArgument
    259  * @retval FwdLockConv_Status_OutOfMemory
    260  * @retval FwdLockConv_Status_FileNotFound
    261  * @retval FwdLockConv_Status_FileCreationFailed
    262  * @retval FwdLockConv_Status_FileReadError
    263  * @retval FwdLockConv_Status_FileWriteError
    264  * @retval FwdLockConv_Status_FileSeekError
    265  * @retval FwdLockConv_Status_SyntaxError
    266  * @retval FwdLockConv_Status_UnsupportedFileFormat
    267  * @retval FwdLockConv_Status_UnsupportedContentTransferEncoding
    268  * @retval FwdLockConv_Status_RandomNumberGenerationFailed
    269  * @retval FwdLockConv_Status_KeyEncryptionFailed
    270  * @retval FwdLockConv_Status_DataEncryptionFailed
    271  * @retval FwdLockConv_Status_IntegrityProtectionFailed
    272  * @retval FwdLockConv_Status_TooManySessions
    273  */
    274 FwdLockConv_Status_t FwdLockConv_ConvertFile(const char *pInputFilename,
    275                                              const char *pOutputFilename,
    276                                              off64_t *pErrorPos);
    277 
    278 #ifdef __cplusplus
    279 }
    280 #endif
    281 
    282 #endif // __FWDLOCKCONV_H__
    283