File content as of revision 11:b6e6519688e8:

/* Copyright C2014 ARM, MIT License
 *
 * Author: Doug Anson (doug.anson@arm.com)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
 * and associated documentation files the "Software", to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge, publish, distribute,
 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all copies or
 * substantial portions of the Software.
 *
 * 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 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, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
 #ifndef _SALESFORCE_INTERFACE_H_
 #define _SALESFORCE_INTERFACE_H_
 
 // ErrorHandler
 #include "ErrorHandler.h"
 
 // SSL-based HTTP support
 #include "HTTPClient.h"
 
 // JSON parsing support
 #include "MbedJSONValue.h"
 
 // verbose debugging
 #if ENABLE_DEBUG_LOGGING
    #define DEBUG(...)                  { this->logger()->logConsole(__VA_ARGS__); }
 #else
    #define DEBUG(...)
 #endif 
 
 // convenience macros
 #define  DEFINE_BUFFER(x)              char x[MAX_BUFFER_LENGTH+1]
 #define  RESET_BUFFER(x)               memset(x,0,MAX_BUFFER_LENGTH+1)
 #define  ALLOC_BUFFER(x)               DEFINE_BUFFER(x);RESET_BUFFER(x)
 
 #define  DEFINE_SML_BUFFER(x)          char x[MAX_SMALL_BUFFER_LENGTH+1]
 #define  RESET_SML_BUFFER(x)           memset(x,0,MAX_SMALL_BUFFER_LENGTH+1)
 #define  ALLOC_SML_BUFFER(x)           DEFINE_SML_BUFFER(x);RESET_SML_BUFFER(x)
 
 // Default salesforce API version (must be in XX.Y format and must be a string)
 #define SALESFORCE_API_VERSION_LENGTH  10
 #ifndef SALESFORCE_API_VERSION
    #define SALESFORCE_API_VERSION      "28.0"
 #endif
 
 // HTTP Verbs
 typedef enum {
     GET,
     PUT,
     POST,
     DELETE,
     NUM_VERBS
 } HttpVerb;
 
 // Supported input data types for PUT and POST (Defined by HTTPClient-SSL/data support...)
 typedef enum {
     JSON,              // ContentType: application/json
     PLAIN_TEXT,        // ContentType: plain/text
     FORM_MAPPED,       // ContentType: application/x-www-form-urlencoded
     NUM_TYPES
 } InputDataTypes;
 
 // OAUTH structure
 typedef struct {
     bool   valid;
     string id;
     string issued_at;
     string token_type;
     string instance_url;
     string signature;
     string access_token;
 } OauthToken;
 
 /**Salesforce Interface 
 SalesforceInterface provides a simple C++ API into the REST-based Salesforce.com APIs
 */       
 class SalesforceInterface {
    private:
        ErrorHandler    *m_logger;
        HTTPClient      *m_http;
        char            *m_username;
        char            *m_password;
        char            *m_client_id;
        char            *m_client_secret;
        bool             m_have_creds;
        OauthToken       m_oauth_token;
        HTTPResult       m_http_status;
        int              m_http_response_code;
        char             m_http_redirection_url[MAX_BUFFER_LENGTH+1];
        char             m_salesforce_id[MAX_BUFFER_LENGTH+1];
        char             m_salesforce_api[SALESFORCE_API_VERSION_LENGTH];
        
    public:
        /**
        Default constructor
        @param logger ErrorHandler instance
        @param http HTTPClient instance
        */
        SalesforceInterface(ErrorHandler *logger,HTTPClient *http); 
        
        /**
        Default destructor
        */
        virtual ~SalesforceInterface();
        
        /**
        Establish salesforce.com credentials
        @param username salesforce.com account user name
        @param password salesfroce.com account password. The password must be of the form [password][security token]
        @param client_id salesforce.com connected application "customer key" value
        @param client_secret salesfroce.com connected application client secret value
        */
        void setCredentials(char *username,char *password,char *client_id,char *client_secret);
        
        /**
        Get our salesforce.com ID
        @param fetch boolean that will direct the interface to fetch the ID if not already done (default = true)
        @return our salesforce ID in JSON format or NULL if in error
        */
        char *getSalesforceID(bool fetch = true);
        
        /**
        Force the interface to re-acquire the OAUTH token and salesforce ID
        */
        void resetSalesforceID();
        
        /**
        Set our salesforce.com API version
        @param version integer value (positive)
        */
        void setSalesforceAPIVersion(int version);
        
        /**
        Set our salesforce.com API version
        @param version string value (format "X.Y")
        */
        void setSalesforceAPIVersion(char *version);
        
        /**
        Get our salesforce.com API version
        @return string containing our salesforce.com API version or NULL if in error
        */
        char *getSalesforceAPIVersion();
        
        /**
        Salesforce.com API SQL QUERY method to invoke ad-hoc SQL queries into salesforce.com
        @param query_str character string with the SQL query to invoke
        @param output_buffer allocated result buffer to use
        @param output_buffer_length allocated result buffer length
        @return result of the SQL query in JSON format or NULL if in error
        */
        char *query(char *query_str,char *output_buffer,int output_buffer_length);
 
        /**
        Salesforce.com API field creation method to create a new field within a salesforce.com object
        @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
        @param field MbedJSONValue json structure that the new field will be comprised with 
        @return MbedJSONValue structure with the results of the creation operation in JSON format
        */
        MbedJSONValue createField(char *object_name,MbedJSONValue &field);
        
        /**
        Salesforce.com API field read method to read a field within a salesforce.com object
        @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
        @param field_id salesforce.com ID of the field instance to read 
        @return MbedJSONValue structure with the results of the read operation in JSON format
        */
        MbedJSONValue readField(char *object_name,char *field_id);
        
        /**
        Salesforce.com API field update method to update a field within a salesforce.com object
        @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
        @param field_id salesforce.com ID of the field instance to read 
        @param field MbedJSONValue instance with updated data for the field
        @return true - success, false - failure
        */
        bool updateField(char *object_name,char *field_id,MbedJSONValue &field);
        
        /**
        Salesforce.com API field delete method to delete a field within a salesforce.com object
        @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
        @param field_id salesforce.com ID of the field instance to delete 
        @return true - success, false - failure
        */
        bool deleteField(char *object_name,char *field_id);
        
        /**
        Salesforce.com API invocation HTTP response code to aid in debugging error conditions
        @return http response code
        */
        // HTTP Error code access
        int httpResponseCode();
                      
 protected: 
        // do we have a valid salesforce ID and OAUTH token?
        bool haveSalesforceID(bool fetch = true);

        // CREATE: a field in Salesforce.com
        char *createField(char *object_name,char *json_data,char *output_buffer,int output_buffer_length);
        
        // READ: a specific field in Salesforce.com
        char *readField(char *object_name,char *field_id,char *output_buffer,int output_buffer_length);
        
        // UPDATE: a specific field in Salesforce.com
        bool updateField(char *object_name,char *field_id,char *json_data);
                            
        // raw invocation of REST calls into Salesforce.com
        char *invoke(const char *url,char *output_buffer,int output_buffer_length);                                                                                                        // defaults to GET
        char *invoke(const char *url,char *output_buffer,int output_buffer_length,HttpVerb verb);                                                                                          // GET or DELETE with simple output
        char *invoke(const char *url,const char *input_data,const int input_data_len,char *output_buffer,int output_buffer_length);                                                        // defaults to POST with JSON input data type
        char *invoke(const char *url,const InputDataTypes input_type,const char *input_data,const int input_data_len,char *output_buffer,int output_buffer_length);                        // defaults to POST with variable input data type
        char *invoke(const char *url,const InputDataTypes input_type,const char *input_data,const int input_data_len,char *output_buffer,int output_buffer_length,const HttpVerb verb);    // full fidelity method
      
        // get our OAUTH Token
        void checkAndGetOauthToken(bool fetch = true);
        char *getOauthToken(char *output_buffer,int output_buffer_length);
     
        // convenience accessors
        ErrorHandler *logger();
        HTTPClient *http();
        OauthToken *oauth();
        HTTPResult httpStatus();
        
        // internal checkers
        bool haveCreds();
        void resetOauthToken();
        void fillOauthToken(char *token);
        bool validOauthToken(bool fetch = true);
        
        // get the specified URL from our Salesforce ID
        char *getSalesforceURL(char *key,char *url_buffer,int url_buffer_length);
       
        // simple char array replacement (modifies input string!)
        void replace(char *str,char orig_char,char new_char);
        
        // needed to replace substrings within std::string
        void replace(string& line, string& oldString, string& newString);
 };
 
 #endif // _SALESFORCE_INTERFACE_H_