text: /*
   Copyright 2011 TweetDeck Inc. All rights reserved.
  
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions are met:
  
   1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.
  
   2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
  
   THIS SOFTWARE IS PROVIDED BY TWEETDECK INC. ``AS IS'' AND ANY EXPRESS OR
   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
   EVENT SHALL TWEETDECK INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  
   The views and conclusions contained in the software and documentation are
   those of the authors and should not be interpreted as representing official
   policies, either expressed or implied, of TweetDeck Inc.
  */
  
  #import <Foundation/Foundation.h>
  #import <Availability.h>
  
  
  FOUNDATION_EXPORT double TDOAuthVersionNumber;
  FOUNDATION_EXPORT const unsigned char TDOAuthVersionString[];
  
  #if (defined(__IPHONE_8_0) && (__IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_8_0)) || \
      (defined(__MAC_10_0)  && (__MAC_OS_X_VERSION_MAX_ALLOWED >= __MAC_10_10))
  #define USE_NSURLCOMPONENTS
  #endif
  
  typedef NS_ENUM(NSInteger, TDOAuthSignatureMethod) {
      TDOAuthSignatureMethodHmacSha1,
      TDOAuthSignatureMethodHmacSha256,
  };
  typedef NS_ENUM(NSInteger, TDOAuthContentType) {
      TDOAuthContentTypeUrlEncodedForm,
      TDOAuthContentTypeJsonObject,
      TDOAuthContentTypeUrlEncodedQuery,
  };
  
  /**
    This OAuth implementation doesn't cover the whole spec (eg. it’s HMAC only).
    But you'll find it works with almost all the OAuth implementations you need
    to interact with in the wild. How ace is that?!
  */
  
  @interface TDOAuth : NSObject
  /**
    @p unencodeParameters may be nil. Objects in the dictionary must be strings.
    You are contracted to consume the NSURLRequest *immediately*. Don't put the
    queryParameters in the path as a query string! Path MUST start with a slash!
    Don't percent encode anything! This will submit via HTTP. If you need HTTPS refer
    to the next selector.
  */
  + (NSURLRequest *)URLRequestForPath:(NSString *)unencodedPath_WITHOUT_Query
                        GETParameters:(NSDictionary *)unencodedParameters
                                 host:(NSString *)host
                          consumerKey:(NSString *)consumerKey
                       consumerSecret:(NSString *)consumerSecret
                          accessToken:(NSString *)accessToken
                          tokenSecret:(NSString *)tokenSecret;
  
  /**
    Some services insist on HTTPS. Or maybe you don't want the data to be sniffed.
    You can pass @"https" via the scheme parameter.
  */
  + (NSURLRequest *)URLRequestForPath:(NSString *)unencodedPath_WITHOUT_Query
                        GETParameters:(NSDictionary *)unencodedParameters
                               scheme:(NSString *)scheme
                                 host:(NSString *)host
                          consumerKey:(NSString *)consumerKey
                       consumerSecret:(NSString *)consumerSecret
                          accessToken:(NSString *)accessToken
                          tokenSecret:(NSString *)tokenSecret;
  
  #ifdef USE_NSURLCOMPONENTS
  /**
    Allow to pass NSURLComponents. READ THE DOCUMENTATION IN PREVIOUS GET METHODS!
   */
  + (NSURLRequest *)URLRequestForGETURLComponents:(NSURLComponents *)urlComponents
                                      consumerKey:(NSString *)consumerKey
                                   consumerSecret:(NSString *)consumerSecret
                                      accessToken:(NSString *)accessToken
                                      tokenSecret:(NSString *)tokenSecret;
  #endif
  /**
    We always POST with HTTPS. This is because at least half the time the user's
    data is at least somewhat private, but also because apparently some carriers
    mangle POST requests and break them. We saw this in France for example.
    READ THE DOCUMENTATION FOR GET AS IT APPLIES HERE TOO!
  */
  + (NSURLRequest *)URLRequestForPath:(NSString *)unencodedPath
                       POSTParameters:(NSDictionary *)unencodedParameters
                                 host:(NSString *)host
                          consumerKey:(NSString *)consumerKey
                       consumerSecret:(NSString *)consumerSecret
                          accessToken:(NSString *)accessToken
                          tokenSecret:(NSString *)tokenSecret;
  
  /**
   This method allows the caller to specify particular values for many different parameters such
   as scheme, method, header values and alternate signature hash algorithms.
  
   @p scheme may be any string value, generally "http" or "https".
   @p requestMethod may be any string value. There is no validation, so remember that all
   currently-defined HTTP methods are uppercase and the RFC specifies that the method
   is case-sensitive.
   @p dataEncoding allows for the transmission of data as either URL-encoded form data,
   query string or JSON by passing the value TDOAuthContentTypeUrlEncodedForm,
   TDOAuthContentTypeUrlEncodedQuery or TDOAuthContentTypeJsonObject.
   This parameter is ignored for the requestMethod "GET".
   @p headerValues accepts a hash of key-value pairs (both must be strings) that specify
   HTTP header values to be included in the resulting URL Request. For example, the argument
   value @{@"Accept": @"application/json"} will include the header to indicate the server
   should respond with JSON. Other values are acceptable, depending on the server, but be
   careful. Values you supply will override the defaults which are set for User-Agent
   (set to "app-bundle-name/version" your app resources), Accept-Encoding (set to "gzip")
   and the calculated Authentication header. Attempting to specify the latter will be fatal.
   You should also avoid passing in values for the Content-Type and Content-Length header fields.
   @p signatureMethod accepts an enum and should normally be set to TDOAuthSignatureMethodHmacSha1.
   You have the option of using HMAC-SHA256 by setting this parameter to
   TDOAuthSignatureMethodHmacSha256; this is not included in the RFC for OAuth 1.0a, so most servers
   will not support it.
  */
  
  + (NSURLRequest *)URLRequestForPath:(NSString *)unencodedPathWithoutQuery
                           parameters:(NSDictionary *)unencodedParameters
                                 host:(NSString *)host
                          consumerKey:(NSString *)consumerKey
                       consumerSecret:(NSString *)consumerSecret
                          accessToken:(NSString *)accessToken
                          tokenSecret:(NSString *)tokenSecret
                               scheme:(NSString *)scheme
                        requestMethod:(NSString *)method
                         dataEncoding:(TDOAuthContentType)dataEncoding
                         headerValues:(NSDictionary *)headerValues
                      signatureMethod:(TDOAuthSignatureMethod)signatureMethod;
  
  /**
  
   OAuth requires the UTC timestamp we send to be accurate. The user's device
   may not be, and often isn't. To work around this you should set this to the
   UTC timestamp that you get back in HTTP headers from OAuth servers.
   */
  +(int)utcTimeOffset;
  +(void)setUtcTimeOffset:(int)offset;
  
  @end
  
  
  /**
    XAuth example (because you may otherwise be scratching your head):
  
      NSURLRequest *xauth = [TDOAuth URLRequestForPath:@"/oauth/access_token"
                                        POSTParameters:[NSDictionary dictionaryWithObjectsAndKeys:
                                                        username, @"x_auth_username",
                                                        password, @"x_auth_password",
                                                        @"client_auth", @"x_auth_mode",
                                                        nil]
                                                  host:@"api.twitter.com"
                                           consumerKey:CONSUMER_KEY
                                        consumerSecret:CONSUMER_SECRET
                                           accessToken:nil
                                           tokenSecret:nil];
  
    OAuth Echo example (we have found that some consumers require HTTPS for the
    echo, so to be safe we always do it):
  
      NSURLRequest *echo = [TDOAuth URLRequestForPath:@"/1/account/verify_credentials.json"
                                        GETParameters:nil
                                               scheme:@"https"
                                                 host:@"api.twitter.com"
                                          consumerKey:CONSUMER_KEY
                                       consumerSecret:CONSUMER_SECRET
                                          accessToken:accessToken
                                          tokenSecret:tokenSecret];
      NSMutableURLRequest *rq = [NSMutableURLRequest new];
      [rq setValue:[[echo URL] absoluteString] forHTTPHeaderField:@"X-Auth-Service-Provider"];
      [rq setValue:[echo valueForHTTPHeaderField:@"Authorization"] forHTTPHeaderField:@"X-Verify-Credentials-Authorization"];
      // Now consume rq with an NSURLConnection
      [rq release];
  */
  
  
  /**
    Suggested usage would be to make some categories for this class that
    automatically adds both secrets, both tokens and host information. This
    makes usage less cumbersome. Eg:
  
        [TwitterOAuth GET:@"/1/statuses/home_timeline.json"];
        [TwitterOAuth GET:@"/1/statuses/home_timeline.json" queryParameters:dictionary];
  
    At TweetDeck we have TDAccount classes that represent separate user logins
    for different services when instantiated.
  */
  