Interface for invoking Salesforce.com REST calls over SSL with OAUTH authentication. This interface is designed to simplify the interaction between mbed devices and salesforce.com web services.
Dependencies: HTTPClient-SSL MbedJSONValue
Diff: SalesforceInterface.h
- Revision:
- 10:845ea6d00b65
- Parent:
- 9:a254fcd904be
- Child:
- 11:b6e6519688e8
diff -r a254fcd904be -r 845ea6d00b65 SalesforceInterface.h --- a/SalesforceInterface.h Tue Sep 23 05:40:18 2014 +0000 +++ b/SalesforceInterface.h Tue Sep 23 16:15:20 2014 +0000 @@ -79,8 +79,10 @@ string signature; string access_token; } OauthToken; - - // SalesforceInterface provides an API into the REST-based Salesforce.com Force APIs + + /**Salesforce Interface + SalesforceInterface provides a simple C++ API into the REST-based Salesforce.com APIs + */ class SalesforceInterface { private: ErrorHandler *m_logger; @@ -98,39 +100,104 @@ char m_salesforce_api[SALESFORCE_API_VERSION_LENGTH]; public: - // construction/destruction + /** + Default constructor + @param logger ErrorHandler instance + @param http HTTPClient instance + */ SalesforceInterface(ErrorHandler *logger,HTTPClient *http); + + /** + Default destructor + */ virtual ~SalesforceInterface(); - // set Salesforce.com credentials + /** + 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 ID structure from Salesforce + /** + Get our salesforce.com ID + @param fetch boolean that will direct the interface to fetch the ID if not already done (default = false) + @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 + /** + Force the interface to re-acquire the OAUTH token and salesforce ID + */ void resetSalesforceID(); - // set/get our salesforce API version + /** + 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(); - // SQL QUERY: into Salesforce.com + /** + 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); - // CREATE: a field in Salesforce.com + /** + 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 + @param output_buffer_length allocated result buffer length + @return MbedJSONValue structure with the results of the creation operation in JSON format + */ MbedJSONValue createField(char *object_name,MbedJSONValue &field); - // READ: a specific field in Salesforce.com - MbedJSONValue readField(char *object_name,char *object_id); + /** + 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); - // UPDATE: a specific field in Salesforce.com - bool updateField(char *object_name,char *object_id,MbedJSONValue &field); + /** + 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); - // DELETE: a specific field in Salesforce.com - bool deleteField(char *object_name,char *object_id); + /** + 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(); @@ -142,10 +209,10 @@ 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 *object_id,char *output_buffer,int output_buffer_length); + 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 *object_id,char *json_data); + 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