Salesforce.com interface to directly access Salesforce.com
Dependencies: HTTPClient-SSL MbedJSONValue
Dependents: df-2014-salesforce-hrm-k64f
Fork of SalesforceInterface by
SalesforceInterface.h@11:b6e6519688e8, 2014-09-23 (annotated)
- Committer:
- ansond
- Date:
- Tue Sep 23 16:18:58 2014 +0000
- Revision:
- 11:b6e6519688e8
- Parent:
- 10:845ea6d00b65
- Child:
- 12:0e7290e093df
fixed comments
Who changed what in which revision?
User | Revision | Line number | New 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 | 11:b6e6519688e8 | 126 | @param fetch boolean that will direct the interface to fetch the ID if not already done (default = true) |
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 | @return MbedJSONValue structure with the results of the creation operation in JSON format |
ansond | 10:845ea6d00b65 | 168 | */ |
ansond | 9:a254fcd904be | 169 | MbedJSONValue createField(char *object_name,MbedJSONValue &field); |
ansond | 9:a254fcd904be | 170 | |
ansond | 10:845ea6d00b65 | 171 | /** |
ansond | 10:845ea6d00b65 | 172 | Salesforce.com API field read method to read a field within a salesforce.com object |
ansond | 10:845ea6d00b65 | 173 | @param object_name name of the salesforce.com object to create the field in (i.e. "Account") |
ansond | 10:845ea6d00b65 | 174 | @param field_id salesforce.com ID of the field instance to read |
ansond | 10:845ea6d00b65 | 175 | @return MbedJSONValue structure with the results of the read operation in JSON format |
ansond | 10:845ea6d00b65 | 176 | */ |
ansond | 10:845ea6d00b65 | 177 | MbedJSONValue readField(char *object_name,char *field_id); |
ansond | 9:a254fcd904be | 178 | |
ansond | 10:845ea6d00b65 | 179 | /** |
ansond | 10:845ea6d00b65 | 180 | Salesforce.com API field update method to update a field within a salesforce.com object |
ansond | 10:845ea6d00b65 | 181 | @param object_name name of the salesforce.com object to create the field in (i.e. "Account") |
ansond | 10:845ea6d00b65 | 182 | @param field_id salesforce.com ID of the field instance to read |
ansond | 10:845ea6d00b65 | 183 | @param field MbedJSONValue instance with updated data for the field |
ansond | 10:845ea6d00b65 | 184 | @return true - success, false - failure |
ansond | 10:845ea6d00b65 | 185 | */ |
ansond | 10:845ea6d00b65 | 186 | bool updateField(char *object_name,char *field_id,MbedJSONValue &field); |
ansond | 9:a254fcd904be | 187 | |
ansond | 10:845ea6d00b65 | 188 | /** |
ansond | 10:845ea6d00b65 | 189 | Salesforce.com API field delete method to delete a field within a salesforce.com object |
ansond | 10:845ea6d00b65 | 190 | @param object_name name of the salesforce.com object to create the field in (i.e. "Account") |
ansond | 10:845ea6d00b65 | 191 | @param field_id salesforce.com ID of the field instance to delete |
ansond | 10:845ea6d00b65 | 192 | @return true - success, false - failure |
ansond | 10:845ea6d00b65 | 193 | */ |
ansond | 10:845ea6d00b65 | 194 | bool deleteField(char *object_name,char *field_id); |
ansond | 9:a254fcd904be | 195 | |
ansond | 10:845ea6d00b65 | 196 | /** |
ansond | 10:845ea6d00b65 | 197 | Salesforce.com API invocation HTTP response code to aid in debugging error conditions |
ansond | 10:845ea6d00b65 | 198 | @return http response code |
ansond | 10:845ea6d00b65 | 199 | */ |
ansond | 9:a254fcd904be | 200 | // HTTP Error code access |
ansond | 9:a254fcd904be | 201 | int httpResponseCode(); |
ansond | 9:a254fcd904be | 202 | |
ansond | 9:a254fcd904be | 203 | protected: |
ansond | 9:a254fcd904be | 204 | // do we have a valid salesforce ID and OAUTH token? |
ansond | 9:a254fcd904be | 205 | bool haveSalesforceID(bool fetch = true); |
ansond | 9:a254fcd904be | 206 | |
ansond | 9:a254fcd904be | 207 | // CREATE: a field in Salesforce.com |
ansond | 9:a254fcd904be | 208 | char *createField(char *object_name,char *json_data,char *output_buffer,int output_buffer_length); |
ansond | 9:a254fcd904be | 209 | |
ansond | 9:a254fcd904be | 210 | // READ: a specific field in Salesforce.com |
ansond | 10:845ea6d00b65 | 211 | char *readField(char *object_name,char *field_id,char *output_buffer,int output_buffer_length); |
ansond | 9:a254fcd904be | 212 | |
ansond | 9:a254fcd904be | 213 | // UPDATE: a specific field in Salesforce.com |
ansond | 10:845ea6d00b65 | 214 | bool updateField(char *object_name,char *field_id,char *json_data); |
ansond | 9:a254fcd904be | 215 | |
ansond | 8:47db53cd5884 | 216 | // raw invocation of REST calls into Salesforce.com |
ansond | 9:a254fcd904be | 217 | char *invoke(const char *url,char *output_buffer,int output_buffer_length); // defaults to GET |
ansond | 9:a254fcd904be | 218 | char *invoke(const char *url,char *output_buffer,int output_buffer_length,HttpVerb verb); // GET or DELETE with simple output |
ansond | 9:a254fcd904be | 219 | 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 | 220 | 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 | 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,const HttpVerb verb); // full fidelity method |
ansond | 9:a254fcd904be | 222 | |
ansond | 0:518b1ca956fc | 223 | // get our OAUTH Token |
ansond | 9:a254fcd904be | 224 | void checkAndGetOauthToken(bool fetch = true); |
ansond | 0:518b1ca956fc | 225 | char *getOauthToken(char *output_buffer,int output_buffer_length); |
ansond | 8:47db53cd5884 | 226 | |
ansond | 0:518b1ca956fc | 227 | // convenience accessors |
ansond | 0:518b1ca956fc | 228 | ErrorHandler *logger(); |
ansond | 0:518b1ca956fc | 229 | HTTPClient *http(); |
ansond | 7:97ea5ef906f7 | 230 | OauthToken *oauth(); |
ansond | 7:97ea5ef906f7 | 231 | HTTPResult httpStatus(); |
ansond | 7:97ea5ef906f7 | 232 | |
ansond | 7:97ea5ef906f7 | 233 | // internal checkers |
ansond | 0:518b1ca956fc | 234 | bool haveCreds(); |
ansond | 7:97ea5ef906f7 | 235 | void resetOauthToken(); |
ansond | 7:97ea5ef906f7 | 236 | void fillOauthToken(char *token); |
ansond | 9:a254fcd904be | 237 | bool validOauthToken(bool fetch = true); |
ansond | 8:47db53cd5884 | 238 | |
ansond | 8:47db53cd5884 | 239 | // get the specified URL from our Salesforce ID |
ansond | 8:47db53cd5884 | 240 | char *getSalesforceURL(char *key,char *url_buffer,int url_buffer_length); |
ansond | 9:a254fcd904be | 241 | |
ansond | 8:47db53cd5884 | 242 | // simple char array replacement (modifies input string!) |
ansond | 8:47db53cd5884 | 243 | void replace(char *str,char orig_char,char new_char); |
ansond | 8:47db53cd5884 | 244 | |
ansond | 8:47db53cd5884 | 245 | // needed to replace substrings within std::string |
ansond | 8:47db53cd5884 | 246 | void replace(string& line, string& oldString, string& newString); |
ansond | 0:518b1ca956fc | 247 | }; |
ansond | 0:518b1ca956fc | 248 | |
ansond | 0:518b1ca956fc | 249 | #endif // _SALESFORCE_INTERFACE_H_ |