OoyalaAPI.h

/**
 * Copyright 2011 © Ooyala, Inc.  All rights reserved.
 * 
 * Ooyala, Inc. (“Ooyala”) hereby grants permission, free of charge, to any person or entity obtaining a copy of the software code provided in source code format via this webpage and direct links contained within this webpage and any associated documentation (collectively, the "Software"), to use, copy, modify, merge, and/or publish the Software and, subject to pass-through of all terms and conditions hereof, permission to transfer, distribute and sublicense the Software; all of the foregoing subject to the following terms and conditions:
 * 
 * 1.  The above copyright notice and this permission notice shall be included in all copies or portions of the Software.
 * 
 * 2.   For purposes of clarity, the Software does not include any APIs, but instead consists of code that may be used in conjunction with APIs that may be provided by Ooyala pursuant to a separate written agreement subject to fees.  
 * 
 * 3.   Ooyala may in its sole discretion maintain and/or update the Software.  However, the Software is provided without any promise or obligation of support, maintenance or update.  
 * 
 * 4.  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, RELATING TO, ARISING FROM, IN CONNECTION WITH, OR INCIDENTAL TO THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 * 
 * 5.   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, (i) IN NO EVENT SHALL OOYALA BE LIABLE FOR ANY CONSEQUENTIAL, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) RELATING TO, ARISING FROM, IN CONNECTION WITH, OR INCIDENTAL TO THE SOFTWARE OR THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF OOYALA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND (ii) OOYALA’S TOTAL AGGREGATE LIABILITY RELATING TO, ARISING FROM, IN CONNECTION WITH, OR INCIDENTAL TO THE SOFTWARE SHALL BE LIMITED TO THE ACTUAL DIRECT DAMAGES INCURRED UP TO MAXIMUM AMOUNT OF FIFTY DOLLARS ($50).
*/
//
//  OoyalaAPI.h
//  Objective-C
//
//  Created by Justino Mejorada on 8/22/11.
//  Based on V1 created by Aldo Vega on 11/10/10.
//  Copyright 2011 Ooyala. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>

#import <CommonCrypto/CommonDigest.h>
#import "GTMBase64.h"
#import "GTMDefines.h"
#import <MobileCoreServices/MobileCoreServices.h>
#import "CJSONDeserializer.h"
#import "CJSONSerializer.h"

/*! \mainpage Objective-C SDK Main Page
 *
 * \section intro_sec Introduction
 *
 * Ooyala provides a public API to create, modify and delete Assets and Resources.
 *
 * This SDK serves as a wrapper for the API to ease development.
 *
 * This documentation was generated by Doxygen.
 *
 * \section install_sec Getting Started
 *
 * \subsection step1 Read the README file in the github project page.
 * 
 */

typedef void (^OOHelperSuccessBlock)(NSString *);
typedef void (^OOHelperFailureBlock)(NSString *);

/** 
 * \nosubgrouping
 * Class that handles requests to the server
 * and provides low-level functionality to interact
 * with ther server API.
 * @see http://api.ooyala.com/docs/v2/
 */
@interface OoyalaAPI : NSObject {
  
  /**
   * @name IMPLEMENTATION PROPERTIES
   * These properties are specific to the implementation,
   * not part of the API resource model, and they don't 
   * need to be directly used to use the SDK.
   */
  
  //@{
  
  NSString                                *APIKey;                    /**< API key */
  NSString                                *secretKey;                 /**< Secret key */
  BOOL                                     cancelUpload;              /**< Implementation property for chunked uploading */
  
  /**
   * Total number of chunks in the current async upload.
   */
  NSNumber                                *numberOfChunks;
  
  /**
   * Number of chunks that suceed uploading.
   * You can use Key Value Observing for this property to
   * get notifications of when new chunks are uploaded.
   */
  NSNumber                                *numberOfChunksSucceeded;   
  
  /**
   * Percent of progress.
   * You can use Key Value Observing for this property to
   * get notifications of when new chunks are uploaded.
   */
  NSNumber                                *uploadProgressPercent;     
  
  //@}
  
}

// IMPLEMENTATION PROPERTIES

@property (nonatomic, retain)             NSString            *APIKey;
@property (nonatomic, retain)             NSString            *secretKey;

@property (nonatomic)                     BOOL                 cancelUpload;
@property (retain)                        NSNumber            *numberOfChunks;
@property (retain)                        NSNumber            *numberOfChunksSucceeded;
@property (retain)                        NSNumber            *uploadProgressPercent;

/** 
 * @name INITIALIZATION
 * Initialization methods 
 */

//@{

/**
 * Initializes the instance with the default keySet
 * @return An OoyalaAPI object
 */
- (id)init;

/**
 * Initializes the instance with the passed keySetName
 * @param keySetName The name of the keySet
 * @return An OoyalaAPI object
 */
- (id)initWithKeySetName:(NSString *)keySetName;

/**
 * Initializes the instance with the passed keys
 * @param APIKey Your API key
 * @param secretKey Your secret key.
 * @return An OoyalaAPI object
 */
- (id)initWithAPIKey:(NSString *)APIKey andSecretKey:(NSString *)secretKey;

//@}

/** 
 * @name SHORTHAND METHODS
 * Methods intended to ease development.
 * These methods use the default keySet.<br>
 * Class methods.
 */

//@{

/**
 * Gets an OoyalaAPI object using the default keySet.
 * Class method.
 * @return An OoyalaAPI object
 */
+ (OoyalaAPI *)OoyalaAPIObject;

//@}

/** 
 * @name URL GENERATION AND SIGNING
 * Methods that generate the URL to request to the server
 * Instance methods.
 */

//@{

/**
 * Generates an encoded signature for the request - Is called by generateEncodedSignedURLWithHTTPMethod.
 * Instance method.<br>
 * This method is automatically called by 
 * generateEncodedSignedURLWithHTTPMethod.<br>
 * @param HTTPMethod A string specifying the method by which to make
 * the request, for example: GET,POST,PATCH,PUT,DELETE
 * @param requestPath A string specifying the relative request path 
 * in the server. Example: /v2/players
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @see generateEncodedSignedURLWithHTTPMethod
 * @return A string with the encoded signature.
 */
- (NSString *)generateEncodedSignatureWithHTTPMethod:(NSString *)HTTPMethod requestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters andRequestBody:(NSData *)requestBody;

/**
 * Generates an encoded signed URL - Also internally calls generateEncodedSignatureWithHTTPMethod.
 * Instance method.<br>
 * This method calls generateEncodedSignedURLWithHTTPMethod
 * and thus can be used to generate the URL in one step.<br>
 * @param HTTPMethod A string specifying the method by which to make
 * the request, for example: GET,POST,PATCH,PUT,DELETE
 * @param requestPath A string specifying the relative request path 
 * in the server. Example: /v2/players
 * @param usingCacheURL Boolean indicating whether to use the
 * high performance cached API URL or the normal API URL. 
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @see generateEncodedSignatureWithHTTPMethod
 * @return An NSURL object with the encoded signed URL
 */
- (NSURL *)generateEncodedSignedURLWithHTTPMethod:(NSString *)HTTPMethod requestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters usingCacheURL:(BOOL)usingCacheURL andRequestBody:(NSData *)requestBody;

//@}

/** 
 * @name SENDING REQUESTS TO THE SEVER - GENERAL METHODS
 * Methods used to send request to the server.
 * Instance methods.
 */

//@{

/**
 * Sends a general request to the server.
 * Instance method.
 * To know whether the request was succesful read the HTTPURLResponse
 * status code.
 * @param HTTPMethod A string specifying the method by which to make
 * the request, can be one of: GET,POST,PATCH,PUT,DELETE
 * @param requestPath A string specifying the relative shortened request path.
 * That is, instead of  using '/v2/players' one would pass to
 * this function only 'players'.
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @param useCache Boolean indicating whether to use the
 * high performance cached API URL or the normal API URL.
 * The cache URL can only be used for GET requests.
 * @param HTTPURLResponse An HTTPURLResponse object passed by reference,
 * when the server responds contains the status code of the response.
 * @param error An NSError object passed by reference that contains 
 * an error on some cases of failure.
 * @return If the server returns information, an object, 
 * commonly an NSMutableDictionary.
 */
- (id)requestUsingHTTPMethod:(NSString *)HTTPMethod requestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters requestBody:(NSMutableDictionary *)requestBody useCache:(BOOL)useCache HTTPURLResponse:(NSHTTPURLResponse **)HTTPURLResponse andError:(NSError **)error;

//@}

/** 
 * @name SENDING REQUESTS TO THE SERVER - SHORTHAND METHODS
 * Methods used to send request to the server.<br>
 * These methods call the general method requestUsingHTTPMethod.<br>
 * Not all their parameters are required, for exmaple GET requests don't 
 * need a requestBody, but to mantain a similar signature to the 
 * general method, so as to ease code duplication, the parameters
 * remain in the method signature.<br>
 * When a parameter is not required, just send an empty object
 * of its respective type to it.<br>
 * Instance methods.
 */

//@{

/**
 * Sends a GET request to the server.
 * Instance method.
 * To know whether the request was succesful read the HTTPURLResponse
 * status code.
 * @param requestPath A string specifying the relative shortened request path.
 * That is, instead of  using '/v2/players' one would pass to
 * this function only 'players'.
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @param useCache Boolean indicating whether to use the
 * high performance cached API URL or the normal API URL.
 * @param HTTPURLResponse An HTTPURLResponse object passed by reference,
 * when the server responds contains the status code of the response.
 * @param error An NSError object passed by reference that contains 
 * an error on some cases of failure.
 * @return If the server returns information, an object, 
 * commonly an NSMutableDictionary.
 */
- (id)GETWithRequestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters requestBody:(NSMutableDictionary *)requestBody useCache:(BOOL)useCache HTTPURLResponse:(NSHTTPURLResponse **)HTTPURLResponse andError:(NSError **)error;

/**
 * Sends a POST request to the server.
 * Instance method.
 * To know whether the request was succesful read the HTTPURLResponse
 * status code.
 * @param requestPath A string specifying the relative shortened request path.
 * That is, instead of  using '/v2/players' one would pass to
 * this function only 'players'.
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @param HTTPURLResponse An HTTPURLResponse object passed by reference,
 * when the server responds contains the status code of the response.
 * @param error An NSError object passed by reference that contains 
 * an error on some cases of failure.
 * @return If the server returns information, an object, 
 * commonly an NSMutableDictionary.
 */
- (id)POSTWithRequestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters requestBody:(NSMutableDictionary *)requestBody HTTPURLResponse:(NSHTTPURLResponse **)HTTPURLResponse andError:(NSError **)error;

/**
 * Sends a PUT request to the server.
 * Instance method.
 * To know whether the request was succesful read the HTTPURLResponse
 * status code.
 * @param requestPath A string specifying the relative shortened request path.
 * That is, instead of using '/v2/players' one would pass to
 * this function only 'players'.
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @param HTTPURLResponse An HTTPURLResponse object passed by reference,
 * when the server responds contains the status code of the response.
 * @param error An NSError object passed by reference that contains 
 * an error on some cases of failure.
 * @return If the server returns information, an object, 
 * commonly an NSMutableDictionary.
 */
- (id)PUTWithRequestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters requestBody:(NSMutableDictionary *)requestBody HTTPURLResponse:(NSHTTPURLResponse **)HTTPURLResponse andError:(NSError **)error;

/**
 * Sends a PATCH request to the server.
 * Instance method.
 * To know whether the request was succesful read the HTTPURLResponse
 * status code.
 * @param requestPath A string specifying the relative shortened request path.
 * That is, instead of  using '/v2/players' one would pass to
 * this function only 'players'.
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @param HTTPURLResponse An HTTPURLResponse object passed by reference,
 * when the server responds contains the status code of the response.
 * @param error An NSError object passed by reference that contains 
 * an error on some cases of failure.
 * @return If the server returns information, an object, 
 * commonly an NSMutableDictionary.
 */
- (id)PATCHWithRequestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters requestBody:(NSMutableDictionary *)requestBody HTTPURLResponse:(NSHTTPURLResponse **)HTTPURLResponse andError:(NSError **)error;

/**
 * Sends a DELETE request to the server.
 * Instance method.
 * To know whether the request was succesful read the HTTPURLResponse
 * status code.
 * @param requestPath A string specifying the relative shortened request path.
 * That is, instead of  using '/v2/players' one would pass to
 * this function only 'players'.
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param requestBody The data of the request body.
 * @param HTTPURLResponse An HTTPURLResponse object passed by reference,
 * when the server responds contains the status code of the response.
 * @param error An NSError object passed by reference that contains 
 * an error on some cases of failure.
 * @return If the server returns information, an object, 
 * commonly an NSMutableDictionary.
 */
- (id)DELETEWithRequestPath:(NSString *)requestPath queryStringParameters:(NSDictionary *)queryStringParameters requestBody:(NSMutableDictionary *)requestBody HTTPURLResponse:(NSHTTPURLResponse **)HTTPURLResponse andError:(NSError **)error;

//@}

/** 
 * @name UPLOADING FILES TO THE SERVER
 * Methods used to sending requests with bytes to the server.
 * Instance methods.
 */

//@{

/**
 * Uploads a file.
 * Can be used to upload images or videos.
 * Instance method.
 * @param filePath An NSURL specifying the complete local filePath of the 
 * file intended to be uploaded.
 * @param HTTPMethod A string specifying the method by which to make
 * the request, for example: GET,POST,PATCH,PUT,DELETE
 * @param requestPathOrURLString This variable has two possibilites.
 * One being a string specifying the relative shortened request path.
 * That is, instead of  using '/v2/players' one would pass to
 * this function only 'players'.Example: players/:player_id/watermark<br>
 * Or<br>
 * The absolute URL string to which to upload the file. Example:
 * The ones returned by the OOAsset's property uploadingUrls
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param HTTPURLResponse An HTTPURLResponse object passed by reference,
 * when the server responds contains the status code of the response.
 * @param error An NSError object passed by reference that contains 
 * an error on some cases of failure.
 * @return If the server returns information, an object.
 */
- (id)requestToUploadFileWithFilePath:(NSURL *)filePath HTTPMethod:(NSString *)HTTPMethod requestPathOrURLString:(NSString *)requestPathOrURLString queryStringParameters:(NSDictionary *)queryStringParameters HTTPURLResponse:(NSHTTPURLResponse **)HTTPURLResponse andError:(NSError **)error;

/**
 * Uploads a file by chunks.
 * Used to upload videos.<br>
 * Chunks are uploaded on separate threads.<br>
 * You can use the instance properties numberOfChunksSucceeded
 * and uploadProgressPercent using Key Value Observing to get
 * notifications of when new chunks are uploaded.<br>
 * This method does not set the asset status to uploaded or failed.<br>
 * Instance method.<br>
 * @param filePath An NSURL specifying the complete local filePath of the 
 * file intended to be uploaded.
 * @param HTTPMethod A string specifying the method by which to make
 * the request, for example: GET,POST,PATCH,PUT,DELETE
 * @param uploadingUrlsArrayOfStrings An array of strings specifying
 * the absolute URL strings to which to upload the file. Example:
 * The ones returned by the OOAsset's property uploadingUrls
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param chunkSize A number specifying the chunk size of the upload. This
 * number must be the same that was passed to the server when creating the 
 * Asset. The suggested chunk size is 2048000.
 * @param maxConcurrentUploads The number of max concurrent uploads required.
 * Example: 20.
 * @param maxNumberOfRetries The number of max number of retries each chunk is 
 * allowed. When a chunk fails to upload a number of times that exceed this value,
 * the upload is canceled. 
 * Example: 3.
 * @return Boolean indicating success.
 */
- (BOOL)requestToUploadFileByChunksWithFilePath:(NSURL *)filePath HTTPMethod:(NSString *)HTTPMethod uploadingUrlsArrayOfStrings:(NSArray *)uploadingUrlsArrayOfStrings queryStringParameters:(NSDictionary *)queryStringParameters chunkSize:(NSNumber *)chunkSize maxConcurrentUploads:(NSNumber *)maxConcurrentUploads maxNumberOfRetries:(NSNumber *)maxNumberOfRetries;

/**
 * Uploads a file by chunks asynchronously.
 * Used to upload videos.<br>
 * Chunks are uploaded on different threads.<br>
 * This method ends its execution almost instantly,
 * and when the upload succeeds or fails the passed
 * code blocks are called.<br>
 * When the file is succesfully uploaded the 
 * You can use the instance properties numberOfChunksSucceeded
 * and uploadProgressPercent using Key Value Observing to get
 * notifications of when new chunks are uploaded.<br>
 * Instance method.
 * @see numberOfChunksSucceeded
 * @see uploadProgressPercent
 * @param filePath An NSURL specifying the complete local filePath of the 
 * file intended to be uploaded.
 * @param HTTPMethod A string specifying the method by which to make
 * the request, for example: GET,POST,PATCH,PUT,DELETE
 * @param uploadingUrlsArrayOfStrings An array of strings specifying
 * the absolute URL strings to which to upload the file. Example:
 * The ones returned by the OOAsset's property uploadingUrls
 * @param queryStringParameters A dictionary with key/value pairs for
 * each parameter of the query string desired. Example: expires -> 111111
 * @param chunkSize A number specifying the chunk size of the upload. This
 * number must be the same that was passed to the server when creating the 
 * Asset. The suggested chunk size is 2048000.
 * @param maxConcurrentUploads The number of max concurrent uploads required.
 * Example: 20.
 * @param maxNumberOfRetries The number of max number of retries each chunk is 
 * allowed. When a chunk fails to upload a number of times that exceed this value,
 * the upload is canceled. 
 * Example: 3.
 * @param successBlock The code block that is executed upon success of the 
 * upload.
 * @param failureBlock The code block that is executed upon failure of the 
 * upload. You can check the passed NSString inside the failureBlock to 
 * check the case of failure.
 * @param assetObjectInstance The instance of type OOAsset that has already been
 * previously saved and to which the video is uploaded. It is used if 
 * setTheAssetStatusAtTheEnd is set to a value that evaluates to true
 * , on which case the assetObjectInstance
 * status property is set to "uploaded" and saved to the server on success
 * or set to "failed" and saved to the server on failure.
 * @param setTheAssetStatusAtTheEnd Boolean specifying whether to set the
 * video status to uploaded or failed upon success or failure respectively
 * or not.
 */
- (void)requestToUploadFileAsynchronouslyByChunksWithFilePath:(NSURL *)filePath HTTPMethod:(NSString *)HTTPMethod uploadingUrlsArrayOfStrings:(NSArray *)uploadingUrlsArrayOfStrings queryStringParameters:(NSDictionary *)queryStringParameters chunkSize:(NSNumber *)chunkSize maxConcurrentUploads:(NSNumber *)maxConcurrentUploads maxNumberOfRetries:(NSNumber *)maxNumberOfRetries successBlock:(OOHelperSuccessBlock)successBlock failureBlock:(OOHelperFailureBlock)failureBlock assetObjectInstance:(id)assetObjectInstance setTheAssetStatusAtTheEnd:(BOOL)setTheAssetStatusAtTheEnd;

//@}

@end