Writing a Client Application Using the IoTC Agent SDK

To write a client application using the IoTC Agent SDK, perform the following steps.

Procedure

1. Define an identifier for the client application:

   IotcApplicationId clientAppId;
   strncpy(clientAppId.id, "com.myclient", sizeof clientAppId.id);

2. Establish a session between the client application andIoTC Agent:

   IotcSession *session;
   session = Iotc_Init(&clientAppId);
   if (session == NULL) {
      // Handle failure 
   }

3. After establishing a session, the client can invoke other APIs to perform operations.
   Currently, the IoTC Agent API works in an asynchronous mode. When an API is invoked, a request is sent to the IoTC Agent and the API returns to the client. Now, the client invokes the Iotc_GetResponse() API to receive a response from the previously invoked API. For example:

   /** Enrollment wrapper function */
   static int
   EnrollGateway(IotcSession *session,
         const char* templateName,
         const char* gatewayName,
         const char* username,
         const char* password)
   {
      IotcEnrollmentRequest enrollmentRequest;
      IotcGetResponse getResponse;
      IotcEnrollmentResponse *resp;
      int status;
    
      enrollmentRequest.data.type = IOTC_NOT_REGISTERED;
      strncpy(enrollmentRequest.data.deviceDetails.deviceTemplate,
            templateName,
            sizeof enrollmentRequest.data.deviceDetails.deviceTemplate);
      enrollmentRequest.data.deviceDetails.deviceTemplate
         [sizeof enrollmentRequest.data.deviceDetails.deviceTemplate - 1] = '\0';
      strncpy(enrollmentRequest.data.deviceDetails.name, gatewayName,
            sizeof enrollmentRequest.data.deviceDetails.name);
      enrollmentRequest.data.deviceDetails.name
         [sizeof enrollmentRequest.data.deviceDetails.name - 1] = '\0';
      strncpy(enrollmentRequest.userCredentials.username,
            username,
            sizeof enrollmentRequest.userCredentials.username);
      enrollmentRequest.userCredentials.username
         [sizeof enrollmentRequest.userCredentials.username - 1] = '\0';
      strncpy(enrollmentRequest.userCredentials.password,
            password,
            sizeof enrollmentRequest.userCredentials.password);
      enrollmentRequest.userCredentials.password
         [sizeof enrollmentRequest.userCredentials.password - 1] = '\0';
    
      if (Iotc_Enroll(session, &enrollmentRequest) == -1) {
         fprintf(stderr, "Failed sending enroll request\n");
         return -1;
      }
    
      /* Invoke GetResponse by supplying type of response */
      status = Iotc_GetResponseByType(session, IOTC_ENROLL_RESPONSE,
                                      CLIENT_TIMEOUT, &getResponse);
      if (status == -1) {
         fprintf(stderr, "Enroll response failed for this client\n");
         return -1;
      }
    
      /* if the GeResponse succeeded, fetch the response */
      resp = getResponse.response;
      printf("Device Id: %s\nParent Device Id: %s\n",
            resp->deviceId.id, resp->parentId.id);
      printf("Status of enroll response: %d\n", status);
    
      /* Cleanup the memory used by the response object */
      Iotc_FreeGetResponse(&getResponse);
      return 0;
   }

4. To disconnect a client from the IoTC Agent, invoke the following API:

   Iotc_Close(session);

Example: Sample MyClient Source Code

/* ****************************************************
 * Copyright (C) 2019 VMware, Inc. All rights reserved.
 * -- VMware Confidential
 * ***************************************************/
 
/**
 * @file MyClient.c
 * @brief This file contains simple example code to demonstrate use of
 * iotc-agent-sdk APIs.
 * This example show how to use Iotc_Enroll API. Users can invoke
 * other APIs in similar manner.
 * This file also offers a utility function to read responses for a
 * API request.
 *
 * note: This is a simple demo example code.
 */
 
#include <stdio.h>
#include <string.h>
 
#include "iotcAgent.h"
 
/* timeout for waiting response from agent (in milliseconds) */
#define CLIENT_TIMEOUT  30000
 
/** Enrollment wrapper function */
static int
EnrollGateway(IotcSession *session,
      const char* templateName,
      const char* gatewayName,
      const char* username,
      const char* password)
{
   IotcEnrollmentRequest enrollmentRequest;
   IotcGetResponse getResponse;
   IotcEnrollmentResponse *resp;
   int status;
 
   enrollmentRequest.data.type = IOTC_NOT_REGISTERED;
   strncpy(enrollmentRequest.data.deviceDetails.deviceTemplate,
         templateName,
         sizeof enrollmentRequest.data.deviceDetails.deviceTemplate);
   enrollmentRequest.data.deviceDetails.deviceTemplate
      [sizeof enrollmentRequest.data.deviceDetails.deviceTemplate - 1] = '\0';
   strncpy(enrollmentRequest.data.deviceDetails.name, gatewayName,
         sizeof enrollmentRequest.data.deviceDetails.name);
   enrollmentRequest.data.deviceDetails.name
      [sizeof enrollmentRequest.data.deviceDetails.name - 1] = '\0';
   strncpy(enrollmentRequest.userCredentials.username,
         username,
         sizeof enrollmentRequest.userCredentials.username);
   enrollmentRequest.userCredentials.username
      [sizeof enrollmentRequest.userCredentials.username - 1] = '\0';
   strncpy(enrollmentRequest.userCredentials.password,
         password,
         sizeof enrollmentRequest.userCredentials.password);
   enrollmentRequest.userCredentials.password
      [sizeof enrollmentRequest.userCredentials.password - 1] = '\0';
 
   if (Iotc_Enroll(session, &enrollmentRequest) == -1) {
      fprintf(stderr, "Failed sending enroll request\n");
      return -1;
   }
 
   /* Invoke GetResponse by supplying type of response */
   status = Iotc_GetResponseByType(session, IOTC_ENROLL_RESPONSE,
                                   CLIENT_TIMEOUT, &getResponse);
   if (status == -1) {
      fprintf(stderr, "Enroll response failed for this client\n");
      return -1;
   }
 
   /* if the GeResponse succeeded, fetch the response */
   resp = getResponse.response;
   printf("Device Id: %s\nParent Device Id: %s\n",
         resp->deviceId.id, resp->parentId.id);
   printf("Status of enroll response: %d\n", status);
 
   /* Cleanup the memory used by the response object */
   Iotc_FreeGetResponse(&getResponse);
   return 0;
}
 
 
int main(int argc, char *argv[])
{
   IotcSession *session;
   IotcApplicationId clientAppId;
   const char *usage = "<template name> <gateway name> <username> <password>";
 
   if (argc != 5) {
      fprintf(stderr, "Usage:\n %s %s\n", argv[0], usage);
      return 1;
   }
 
   strncpy(clientAppId.id, "com.myclient", sizeof clientAppId.id);
   session = Iotc_Init(&clientAppId);
   if (session == NULL) {
      /* Handle failure */
      fprintf(stderr, "Could not initialize a session with iotc-agent\n");
      return 1;
   }
 
   /* Invoke a iotc-agent sdk API
      Note password is consumed as command line parameter for
      keeping thus example program simple */
   if (EnrollGateway(session, argv[1], argv[2], argv[3], argv[4]) == -1) {
      fprintf(stderr, "Enrollment failed\n");
   }
 
   /* Close the session */
   Iotc_Close(session);
   return 0;
}

What to do next

Build a client that uses the IoTC Agent SDK.