Diff: SalesforceInterface.h

Revision:

10:845ea6d00b65

Parent:

9:a254fcd904be

Child:

11:b6e6519688e8

--- 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