Diff: SalesforceInterface.h

Revision:

13:3088dd4b4bef

Parent:

12:0e7290e093df

Child:

14:3c8d11b48814

--- a/SalesforceInterface.h	Tue Sep 23 16:21:28 2014 +0000
+++ b/SalesforceInterface.h	Tue Sep 23 16:56:25 2014 +0000
@@ -80,8 +80,277 @@
      string access_token;
  } OauthToken;
  
- /**Salesforce Interface 
- SalesforceInterface provides a simple C++ API into the REST-based Salesforce.com APIs
+ /**
+ * Salesforce Interface 
+ * SalesforceInterface provides a simple C++ API into the REST-based Salesforce.com APIs
+ *
+ * Example Project: http://mbed.org/users/ansond/code/df-2014-salesforce-testharness-k64f/ 
+ *
+ * @code
+ * #include "Definitions.h"     // definitions including platform specifics...
+ * #include "ErrorHandler.h"
+ *  
+ * // include salesforce.com credentials
+ * #include "sf_creds.h"
+ *   
+ * // our Serial port
+ * #include "BufferedSerial.h"
+ * BufferedSerial pc(USBTX, USBRX);
+ * 
+ * // Ethernet
+ * #include "EthernetInterface.h"
+ * EthernetInterface ethernet;
+ *  
+ * // HTTP 
+ * #include "HTTPClient.h"
+ * HTTPClient http;
+ * 
+ * // Salesforce.com Interface
+ * #include "SalesforceInterface.h"
+ *  
+ * // test case persistence
+ * char *object_name = NULL;
+ * char *account_name = NULL;
+ * char *updated_account_name = NULL;
+ * DEFINE_SML_BUFFER(field_id);
+ *    
+ * // *************** Test Cases ************************
+ * 
+ * void Test_getSalesforceID(ErrorHandler *logger,SalesforceInterface *sf) {
+ *     logger->log("\r\n\r\nGetting Salesforce ID...");
+ *     logger->turnLEDPurple();
+ *     
+ *     // get the salesforce ID     
+ *     char *id = sf->getSalesforceID();
+ *     if (id != NULL && strlen(id) > 0)
+ *         logger->log("Saleforce ID: %s",id);
+ *     else
+ *         logger->log("Unable to get Saleforce ID");
+ *     logger->turnLEDGreen();
+ * }
+ * 
+ * void Test_query(ErrorHandler *logger,SalesforceInterface *sf,char *query_str) {
+ *     logger->log("\r\n\r\nExecuting test query: %s",query_str);
+ *     logger->turnLEDPurple();
+ *     if (query_str != NULL && strlen(query_str) > 0) { 
+ *         ALLOC_BUFFER(response);
+ *         char *answer = sf->query(query_str,response,MAX_BUFFER_LENGTH);
+ *         if (answer != NULL) logger->log("query result: %s",answer);
+ *         else logger->log("query - NULL result");
+ *     }
+ *     else {
+ *        logger->log("Unable to perform query as we do not have our salesforce ID");
+ *     }
+ *     logger->turnLEDGreen();
+ * }
+ * 
+ * void Test_create(ErrorHandler *logger,SalesforceInterface *sf) {
+ *     logger->log("\r\n\r\nExecuting create()");
+ *     logger->turnLEDPurple();
+ *     
+ *     // create a new field
+ *     MbedJSONValue new_field;
+ *     new_field["name"] = account_name;
+ *     
+ *     // DEBUG
+ *     logger->log("Create: new field: %s",new_field.serialize().c_str());
+ *     
+ *     // create...
+ *     MbedJSONValue response = sf->createField(object_name,new_field);
+ *     
+ *     // display the result
+ *     char *result = (char *)response.serialize().c_str();
+ *     if (result != NULL && strlen(result) > 0 && strcmp(result,"null") != 0) {
+ *        // save off the ID if we succeeded
+ *        logger->log("Create: result: %s",result);
+ *        logger->log("Create: http_code=%d",sf->httpResponseCode());
+ *        RESET_SML_BUFFER(field_id);
+ *        strcpy(field_id,(char *)response["id"].get<std::string>().c_str());
+ *     }
+ *     else {
+ *        // failure
+ *        logger->log("Create: FAILED http_code=%d",sf->httpResponseCode());
+ *     }
+ *     logger->turnLEDGreen();
+ * }
+ * 
+ * void Test_read(ErrorHandler *logger,SalesforceInterface *sf) {
+ *     logger->log("\r\n\r\nExecuting read()");
+ *     logger->turnLEDPurple();
+ *          
+ *     // DEBUG
+ *     logger->log("Read: reading: %s from %s",field_id,object_name);
+ *     
+ *     // read...
+ *     MbedJSONValue response = sf->readField(object_name,field_id);
+ *     
+ *     // display the result
+ *     char *result = (char *)response.serialize().c_str();
+ *     if (result != NULL && strlen(result) > 0 && strcmp(result,"null") != 0) {
+ *        // save off the ID if we succeeded
+ *        logger->log("Read: result: %s",result);
+ *        logger->log("Read: http_code=%d",sf->httpResponseCode());
+ *     }
+ *     else {
+ *        // failure
+ *        logger->log("Read: FAILED http_code=%d",sf->httpResponseCode());
+ *     }
+ *     
+ *     logger->turnLEDGreen();
+ * }
+ * 
+ * void Test_update(ErrorHandler *logger,SalesforceInterface *sf) {
+ *     logger->log("\r\n\r\nExecuting update()");
+ *     logger->turnLEDPurple();
+ *     
+ *     // update am existing field - assume "name" is the proper key for the field you wish to update...
+ *     MbedJSONValue changed_field;
+ *     changed_field["name"] = updated_account_name;
+ *     
+ *     // DEBUG
+ *     logger->log("Update: updated field: %s",changed_field.serialize().c_str());
+ *     
+ *     // update...
+ *     bool updated = sf->updateField(object_name,field_id,changed_field);
+ *     
+ *     // display the result
+ *     if (updated) {
+ *        // SUCCESS
+ *        logger->log("Update: successful! http_code=%d",sf->httpResponseCode());
+ *     }
+ *     else {
+ *        // failure
+ *        logger->log("Update: FAILED http_code=%d",sf->httpResponseCode());
+ *     }
+ *     logger->turnLEDGreen();
+ * }
+ * 
+ * void Test_delete(ErrorHandler *logger,SalesforceInterface *sf) {
+ *     logger->log("\r\n\r\nExecuting delete()");
+ *     logger->turnLEDPurple();
+ *     
+ *     // DEBUG
+ *     logger->log("Delete: deleting: %s from %s",field_id,object_name);
+ *     
+ *     // delete...
+ *     bool deleted = sf->deleteField(object_name,field_id);
+ *     
+ *     // display the result
+ *     if (deleted) {
+ *        // SUCCESS
+ *        logger->log("Delete: successful! http_code=%d",sf->httpResponseCode());
+ *     }
+ *     else {
+ *        // failure
+ *        logger->log("Delete: FAILED http_code=%d",sf->httpResponseCode());
+ *    }
+ *     
+ *     logger->turnLEDGreen();
+ * }
+ *  
+ * void Test_reset_auth(ErrorHandler *logger,SalesforceInterface *sf) {
+ *     logger->log("\r\n\r\nForcing API to reset OAUTH token and Salesforce ID...");
+ *     logger->turnLEDPurple();
+ *     sf->resetSalesforceID();
+ *     logger->turnLEDGreen();
+ * }
+ * 
+ * // *************** Test Cases ************************
+ * 
+ * // Main Task...
+ * void mainTask(void const *v) {
+ *        
+ *    // create our object instances 
+ *    ErrorHandler logger(&pc,NULL);
+ *    SalesforceInterface *sf = NULL;
+ *    
+ *    // announce
+ *    logger.log("\r\n\r\nARM Salesforce Interface TestHarness v%s",APP_VERSION);
+ *    logger.turnLEDBlue();
+ *    
+ *    // initialize Ethernet
+ *    logger.log("Initializing Ethernet...");
+ *    ethernet.init();
+ *    
+ *    // get a DHCP address and bring the network interface up
+ *    logger.log("Getting IP Address...");
+ *    logger.turnLEDOrange();
+ *    if (ethernet.connect() == 0) {
+ *        // log our IP address (DHCP)
+ *        logger.log("IP Address: %s",ethernet.getIPAddress());
+ *        
+ *        // allocate the Salesforce.com interface
+ *        logger.log("Allocating Saleforce.com interface...");
+ *        sf = new SalesforceInterface(&logger,&http);
+ *        
+ *        // set our Salesforce.com credentials
+ *        sf->setCredentials(username,password,client_id,client_secret);
+ *        
+ *        // *************** BEGIN TEST CASES *****************        
+ * 
+ *        // configuration for the test cases        
+ *        object_name          = "Account";       // use the account object
+ *        account_name         = "ARM";           // add this field (name)
+ *        updated_account_name = "ARM Holdings";  // update the existing field's name to this
+ *        RESET_SML_BUFFER(field_id);             // buffer for the field's ID
+ *               
+ *        // Perform a Create
+ *        Test_create(&logger,sf);
+ *                
+ *        // Perform a Read
+ *        Test_read(&logger,sf);
+ *
+ *        // Perform a Query
+ *        Test_query(&logger,sf,"SELECT Id,Name FROM Account LIMIT 5");
+ *        
+ *        // Perform an Update
+ *        Test_update(&logger,sf);
+ *        
+ *        // Perform a second Read to visually confirm the update above...
+ *        Test_read(&logger,sf);
+ *        
+ *        // force the API to re-acquire the OAUTH token and Salesforce ID 
+ *        Test_reset_auth(&logger,sf);
+ *        
+ *        // Perform a Read (should re-acquire the OAUTH token and Salesforce ID)
+ *        Test_read(&logger,sf);
+ *        
+ *        // Perform a Delete
+ *        Test_delete(&logger,sf);
+ *                
+ *        // reset the field ID buffer
+ *        // RESET_SML_BUFFER(field_id);
+ *        
+ *        // Perform a Read - should error out
+ *        Test_read(&logger,sf);
+ *                        
+ *        // reset the field ID buffer
+ *        RESET_SML_BUFFER(field_id);
+ *        
+ *        // *************** BEGIN TEST CASES *****************      
+ *        
+ *        // entering main loop
+ *        logger.log("All tests complete...\r\nExiting...");
+ *        logger.turnLEDBlue();
+ *        exit(0);
+ *     }
+ *     else {
+ *         logger.log("No Network... Exiting...");
+ *         logger.turnLEDRed();
+ *         exit(1);
+ *     }
+ *
+ *  }
+ *  
+ *  // main entry
+ *  int main() {
+ *     Thread workerTask(mainTask, NULL, osPriorityNormal, STACK_SIZE);
+ *     while (true) {
+ *         Thread::wait(10*WAIT_TIME_MS);
+ *     }
+ *  }  
+ * @endcode
+ *
  */       
  class SalesforceInterface {
     private: