MBED_DEMOS / SalesforceInterface

Salesforce.com interface to directly access Salesforce.com

Dependencies:   HTTPClient-SSL MbedJSONValue

Dependents:   df-2014-salesforce-hrm-k64f

Fork of SalesforceInterface by Doug Anson

SalesforceInterface.h@10:845ea6d00b65, 2014-09-23 (annotated)

Committer:
ansond
Date:
Tue Sep 23 16:15:20 2014 +0000
Revision:
10:845ea6d00b65
Parent:
9:a254fcd904be
Child:
11:b6e6519688e8
doxygened

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:518b1ca956fc 1 /* Copyright C2014 ARM, MIT License
ansond 0:518b1ca956fc 2 *
ansond 9:a254fcd904be 3 * Author: Doug Anson (doug.anson@arm.com)
ansond 9:a254fcd904be 4 *
ansond 0:518b1ca956fc 5 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
ansond 0:518b1ca956fc 6 * and associated documentation files the "Software", to deal in the Software without restriction,
ansond 0:518b1ca956fc 7 * including without limitation the rights to use, copy, modify, merge, publish, distribute,
ansond 0:518b1ca956fc 8 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
ansond 0:518b1ca956fc 9 * furnished to do so, subject to the following conditions:
ansond 0:518b1ca956fc 10 *
ansond 0:518b1ca956fc 11 * The above copyright notice and this permission notice shall be included in all copies or
ansond 0:518b1ca956fc 12 * substantial portions of the Software.
ansond 0:518b1ca956fc 13 *
ansond 0:518b1ca956fc 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
ansond 0:518b1ca956fc 15 * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
ansond 0:518b1ca956fc 16 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
ansond 0:518b1ca956fc 17 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
ansond 0:518b1ca956fc 18 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
ansond 0:518b1ca956fc 19 */
ansond 0:518b1ca956fc 20
ansond 0:518b1ca956fc 21 #ifndef _SALESFORCE_INTERFACE_H_
ansond 0:518b1ca956fc 22 #define _SALESFORCE_INTERFACE_H_
ansond 0:518b1ca956fc 23
ansond 0:518b1ca956fc 24 // ErrorHandler
ansond 0:518b1ca956fc 25 #include "ErrorHandler.h"
ansond 0:518b1ca956fc 26
ansond 0:518b1ca956fc 27 // SSL-based HTTP support
ansond 0:518b1ca956fc 28 #include "HTTPClient.h"
ansond 0:518b1ca956fc 29
ansond 0:518b1ca956fc 30 // JSON parsing support
ansond 0:518b1ca956fc 31 #include "MbedJSONValue.h"
ansond 0:518b1ca956fc 32
ansond 0:518b1ca956fc 33 // verbose debugging
ansond 0:518b1ca956fc 34 #if ENABLE_DEBUG_LOGGING
ansond 8:47db53cd5884 35 #define DEBUG(...) { this->logger()->logConsole(__VA_ARGS__); }
ansond 0:518b1ca956fc 36 #else
ansond 0:518b1ca956fc 37 #define DEBUG(...)
ansond 0:518b1ca956fc 38 #endif
ansond 7:97ea5ef906f7 39
ansond 7:97ea5ef906f7 40 // convenience macros
ansond 8:47db53cd5884 41 #define DEFINE_BUFFER(x) char x[MAX_BUFFER_LENGTH+1]
ansond 8:47db53cd5884 42 #define RESET_BUFFER(x) memset(x,0,MAX_BUFFER_LENGTH+1)
ansond 8:47db53cd5884 43 #define ALLOC_BUFFER(x) DEFINE_BUFFER(x);RESET_BUFFER(x)
ansond 8:47db53cd5884 44
ansond 8:47db53cd5884 45 #define DEFINE_SML_BUFFER(x) char x[MAX_SMALL_BUFFER_LENGTH+1]
ansond 8:47db53cd5884 46 #define RESET_SML_BUFFER(x) memset(x,0,MAX_SMALL_BUFFER_LENGTH+1)
ansond 8:47db53cd5884 47 #define ALLOC_SML_BUFFER(x) DEFINE_SML_BUFFER(x);RESET_SML_BUFFER(x)
ansond 8:47db53cd5884 48
ansond 8:47db53cd5884 49 // Default salesforce API version (must be in XX.Y format and must be a string)
ansond 8:47db53cd5884 50 #define SALESFORCE_API_VERSION_LENGTH 10
ansond 8:47db53cd5884 51 #ifndef SALESFORCE_API_VERSION
ansond 8:47db53cd5884 52 #define SALESFORCE_API_VERSION "28.0"
ansond 8:47db53cd5884 53 #endif
ansond 0:518b1ca956fc 54
ansond 0:518b1ca956fc 55 // HTTP Verbs
ansond 0:518b1ca956fc 56 typedef enum {
ansond 0:518b1ca956fc 57 GET,
ansond 0:518b1ca956fc 58 PUT,
ansond 0:518b1ca956fc 59 POST,
ansond 0:518b1ca956fc 60 DELETE,
ansond 0:518b1ca956fc 61 NUM_VERBS
ansond 0:518b1ca956fc 62 } HttpVerb;
ansond 0:518b1ca956fc 63
ansond 0:518b1ca956fc 64 // Supported input data types for PUT and POST (Defined by HTTPClient-SSL/data support...)
ansond 0:518b1ca956fc 65 typedef enum {
ansond 0:518b1ca956fc 66 JSON, // ContentType: application/json
ansond 0:518b1ca956fc 67 PLAIN_TEXT, // ContentType: plain/text
ansond 0:518b1ca956fc 68 FORM_MAPPED, // ContentType: application/x-www-form-urlencoded
ansond 0:518b1ca956fc 69 NUM_TYPES
ansond 0:518b1ca956fc 70 } InputDataTypes;
ansond 0:518b1ca956fc 71
ansond 7:97ea5ef906f7 72 // OAUTH structure
ansond 7:97ea5ef906f7 73 typedef struct {
ansond 7:97ea5ef906f7 74 bool valid;
ansond 7:97ea5ef906f7 75 string id;
ansond 7:97ea5ef906f7 76 string issued_at;
ansond 7:97ea5ef906f7 77 string token_type;
ansond 7:97ea5ef906f7 78 string instance_url;
ansond 7:97ea5ef906f7 79 string signature;
ansond 7:97ea5ef906f7 80 string access_token;
ansond 7:97ea5ef906f7 81 } OauthToken;
ansond 10:845ea6d00b65 82
ansond 10:845ea6d00b65 83 /**Salesforce Interface
ansond 10:845ea6d00b65 84 SalesforceInterface provides a simple C++ API into the REST-based Salesforce.com APIs
ansond 10:845ea6d00b65 85 */
ansond 0:518b1ca956fc 86 class SalesforceInterface {
ansond 0:518b1ca956fc 87 private:
ansond 0:518b1ca956fc 88 ErrorHandler *m_logger;
ansond 0:518b1ca956fc 89 HTTPClient *m_http;
ansond 0:518b1ca956fc 90 char *m_username;
ansond 0:518b1ca956fc 91 char *m_password;
ansond 0:518b1ca956fc 92 char *m_client_id;
ansond 0:518b1ca956fc 93 char *m_client_secret;
ansond 0:518b1ca956fc 94 bool m_have_creds;
ansond 7:97ea5ef906f7 95 OauthToken m_oauth_token;
ansond 7:97ea5ef906f7 96 HTTPResult m_http_status;
ansond 7:97ea5ef906f7 97 int m_http_response_code;
ansond 7:97ea5ef906f7 98 char m_http_redirection_url[MAX_BUFFER_LENGTH+1];
ansond 8:47db53cd5884 99 char m_salesforce_id[MAX_BUFFER_LENGTH+1];
ansond 8:47db53cd5884 100 char m_salesforce_api[SALESFORCE_API_VERSION_LENGTH];
ansond 0:518b1ca956fc 101
ansond 0:518b1ca956fc 102 public:
ansond 10:845ea6d00b65 103 /**
ansond 10:845ea6d00b65 104 Default constructor
ansond 10:845ea6d00b65 105 @param logger ErrorHandler instance
ansond 10:845ea6d00b65 106 @param http HTTPClient instance
ansond 10:845ea6d00b65 107 */
ansond 0:518b1ca956fc 108 SalesforceInterface(ErrorHandler *logger,HTTPClient *http);
ansond 10:845ea6d00b65 109
ansond 10:845ea6d00b65 110 /**
ansond 10:845ea6d00b65 111 Default destructor
ansond 10:845ea6d00b65 112 */
ansond 0:518b1ca956fc 113 virtual ~SalesforceInterface();
ansond 0:518b1ca956fc 114
ansond 10:845ea6d00b65 115 /**
ansond 10:845ea6d00b65 116 Establish salesforce.com credentials
ansond 10:845ea6d00b65 117 @param username salesforce.com account user name
ansond 10:845ea6d00b65 118 @param password salesfroce.com account password. The password must be of the form [password][security token]
ansond 10:845ea6d00b65 119 @param client_id salesforce.com connected application "customer key" value
ansond 10:845ea6d00b65 120 @param client_secret salesfroce.com connected application client secret value
ansond 10:845ea6d00b65 121 */
ansond 0:518b1ca956fc 122 void setCredentials(char *username,char *password,char *client_id,char *client_secret);
ansond 0:518b1ca956fc 123
ansond 10:845ea6d00b65 124 /**
ansond 10:845ea6d00b65 125 Get our salesforce.com ID
ansond 10:845ea6d00b65 126 @param fetch boolean that will direct the interface to fetch the ID if not already done (default = false)
ansond 10:845ea6d00b65 127 @return our salesforce ID in JSON format or NULL if in error
ansond 10:845ea6d00b65 128 */
ansond 9:a254fcd904be 129 char *getSalesforceID(bool fetch = true);
ansond 9:a254fcd904be 130
ansond 10:845ea6d00b65 131 /**
ansond 10:845ea6d00b65 132 Force the interface to re-acquire the OAUTH token and salesforce ID
ansond 10:845ea6d00b65 133 */
ansond 9:a254fcd904be 134 void resetSalesforceID();
ansond 8:47db53cd5884 135
ansond 10:845ea6d00b65 136 /**
ansond 10:845ea6d00b65 137 Set our salesforce.com API version
ansond 10:845ea6d00b65 138 @param version integer value (positive)
ansond 10:845ea6d00b65 139 */
ansond 8:47db53cd5884 140 void setSalesforceAPIVersion(int version);
ansond 10:845ea6d00b65 141
ansond 10:845ea6d00b65 142 /**
ansond 10:845ea6d00b65 143 Set our salesforce.com API version
ansond 10:845ea6d00b65 144 @param version string value (format "X.Y")
ansond 10:845ea6d00b65 145 */
ansond 8:47db53cd5884 146 void setSalesforceAPIVersion(char *version);
ansond 10:845ea6d00b65 147
ansond 10:845ea6d00b65 148 /**
ansond 10:845ea6d00b65 149 Get our salesforce.com API version
ansond 10:845ea6d00b65 150 @return string containing our salesforce.com API version or NULL if in error
ansond 10:845ea6d00b65 151 */
ansond 8:47db53cd5884 152 char *getSalesforceAPIVersion();
ansond 8:47db53cd5884 153
ansond 10:845ea6d00b65 154 /**
ansond 10:845ea6d00b65 155 Salesforce.com API SQL QUERY method to invoke ad-hoc SQL queries into salesforce.com
ansond 10:845ea6d00b65 156 @param query_str character string with the SQL query to invoke
ansond 10:845ea6d00b65 157 @param output_buffer allocated result buffer to use
ansond 10:845ea6d00b65 158 @param output_buffer_length allocated result buffer length
ansond 10:845ea6d00b65 159 @return result of the SQL query in JSON format or NULL if in error
ansond 10:845ea6d00b65 160 */
ansond 8:47db53cd5884 161 char *query(char *query_str,char *output_buffer,int output_buffer_length);
ansond 9:a254fcd904be 162
ansond 10:845ea6d00b65 163 /**
ansond 10:845ea6d00b65 164 Salesforce.com API field creation method to create a new field within a salesforce.com object
ansond 10:845ea6d00b65 165 @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
ansond 10:845ea6d00b65 166 @param field MbedJSONValue json structure that the new field will be comprised with
ansond 10:845ea6d00b65 167 @param output_buffer_length allocated result buffer length
ansond 10:845ea6d00b65 168 @return MbedJSONValue structure with the results of the creation operation in JSON format
ansond 10:845ea6d00b65 169 */
ansond 9:a254fcd904be 170 MbedJSONValue createField(char *object_name,MbedJSONValue &field);
ansond 9:a254fcd904be 171
ansond 10:845ea6d00b65 172 /**
ansond 10:845ea6d00b65 173 Salesforce.com API field read method to read a field within a salesforce.com object
ansond 10:845ea6d00b65 174 @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
ansond 10:845ea6d00b65 175 @param field_id salesforce.com ID of the field instance to read
ansond 10:845ea6d00b65 176 @return MbedJSONValue structure with the results of the read operation in JSON format
ansond 10:845ea6d00b65 177 */
ansond 10:845ea6d00b65 178 MbedJSONValue readField(char *object_name,char *field_id);
ansond 9:a254fcd904be 179
ansond 10:845ea6d00b65 180 /**
ansond 10:845ea6d00b65 181 Salesforce.com API field update method to update a field within a salesforce.com object
ansond 10:845ea6d00b65 182 @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
ansond 10:845ea6d00b65 183 @param field_id salesforce.com ID of the field instance to read
ansond 10:845ea6d00b65 184 @param field MbedJSONValue instance with updated data for the field
ansond 10:845ea6d00b65 185 @return true - success, false - failure
ansond 10:845ea6d00b65 186 */
ansond 10:845ea6d00b65 187 bool updateField(char *object_name,char *field_id,MbedJSONValue &field);
ansond 9:a254fcd904be 188
ansond 10:845ea6d00b65 189 /**
ansond 10:845ea6d00b65 190 Salesforce.com API field delete method to delete a field within a salesforce.com object
ansond 10:845ea6d00b65 191 @param object_name name of the salesforce.com object to create the field in (i.e. "Account")
ansond 10:845ea6d00b65 192 @param field_id salesforce.com ID of the field instance to delete
ansond 10:845ea6d00b65 193 @return true - success, false - failure
ansond 10:845ea6d00b65 194 */
ansond 10:845ea6d00b65 195 bool deleteField(char *object_name,char *field_id);
ansond 9:a254fcd904be 196
ansond 10:845ea6d00b65 197 /**
ansond 10:845ea6d00b65 198 Salesforce.com API invocation HTTP response code to aid in debugging error conditions
ansond 10:845ea6d00b65 199 @return http response code
ansond 10:845ea6d00b65 200 */
ansond 9:a254fcd904be 201 // HTTP Error code access
ansond 9:a254fcd904be 202 int httpResponseCode();
ansond 9:a254fcd904be 203
ansond 9:a254fcd904be 204 protected:
ansond 9:a254fcd904be 205 // do we have a valid salesforce ID and OAUTH token?
ansond 9:a254fcd904be 206 bool haveSalesforceID(bool fetch = true);
ansond 9:a254fcd904be 207
ansond 9:a254fcd904be 208 // CREATE: a field in Salesforce.com
ansond 9:a254fcd904be 209 char *createField(char *object_name,char *json_data,char *output_buffer,int output_buffer_length);
ansond 9:a254fcd904be 210
ansond 9:a254fcd904be 211 // READ: a specific field in Salesforce.com
ansond 10:845ea6d00b65 212 char *readField(char *object_name,char *field_id,char *output_buffer,int output_buffer_length);
ansond 9:a254fcd904be 213
ansond 9:a254fcd904be 214 // UPDATE: a specific field in Salesforce.com
ansond 10:845ea6d00b65 215 bool updateField(char *object_name,char *field_id,char *json_data);
ansond 9:a254fcd904be 216
ansond 8:47db53cd5884 217 // raw invocation of REST calls into Salesforce.com
ansond 9:a254fcd904be 218 char *invoke(const char *url,char *output_buffer,int output_buffer_length); // defaults to GET
ansond 9:a254fcd904be 219 char *invoke(const char *url,char *output_buffer,int output_buffer_length,HttpVerb verb); // GET or DELETE with simple output
ansond 9:a254fcd904be 220 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
ansond 9:a254fcd904be 221 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
ansond 9:a254fcd904be 222 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
ansond 9:a254fcd904be 223
ansond 0:518b1ca956fc 224 // get our OAUTH Token
ansond 9:a254fcd904be 225 void checkAndGetOauthToken(bool fetch = true);
ansond 0:518b1ca956fc 226 char *getOauthToken(char *output_buffer,int output_buffer_length);
ansond 8:47db53cd5884 227
ansond 0:518b1ca956fc 228 // convenience accessors
ansond 0:518b1ca956fc 229 ErrorHandler *logger();
ansond 0:518b1ca956fc 230 HTTPClient *http();
ansond 7:97ea5ef906f7 231 OauthToken *oauth();
ansond 7:97ea5ef906f7 232 HTTPResult httpStatus();
ansond 7:97ea5ef906f7 233
ansond 7:97ea5ef906f7 234 // internal checkers
ansond 0:518b1ca956fc 235 bool haveCreds();
ansond 7:97ea5ef906f7 236 void resetOauthToken();
ansond 7:97ea5ef906f7 237 void fillOauthToken(char *token);
ansond 9:a254fcd904be 238 bool validOauthToken(bool fetch = true);
ansond 8:47db53cd5884 239
ansond 8:47db53cd5884 240 // get the specified URL from our Salesforce ID
ansond 8:47db53cd5884 241 char *getSalesforceURL(char *key,char *url_buffer,int url_buffer_length);
ansond 9:a254fcd904be 242
ansond 8:47db53cd5884 243 // simple char array replacement (modifies input string!)
ansond 8:47db53cd5884 244 void replace(char *str,char orig_char,char new_char);
ansond 8:47db53cd5884 245
ansond 8:47db53cd5884 246 // needed to replace substrings within std::string
ansond 8:47db53cd5884 247 void replace(string& line, string& oldString, string& newString);
ansond 0:518b1ca956fc 248 };
ansond 0:518b1ca956fc 249
ansond 0:518b1ca956fc 250 #endif // _SALESFORCE_INTERFACE_H_