Usage example

Step 1: Initialization

1. Add the header file.
   

   ……
   ……
   
   #include "aiot_ra_api.h"

   
   

2. Configure underlying dependencies and log output.

       aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
       aiot_state_set_logcb(demo_state_logcb);

3. Call aiot_ra_init to create an RA

       void *ra_handle = aiot_ra_init();
       if (ra_handle == NULL) {
           printf( "aiot_ra_init failed\n");
           return -1;
       }

Step 2: Configure features

Call aiot_ra_setopt to configure the following features.

1. Configure feature parameters.
   Important Before you configure parameters for the remote logon feature, make sure that you have configured device credentials and other related parameters. For more information, see Configure MQTT connection parameters.

   •     aiot_ra_setopt(ra_handle, AIOT_RAOPT_MQTT_HANDLE, mqtt_handle);
         aiot_ra_setopt(ra_handle, AIOT_RAOPT_NETWORK_CRED, (void *)&cred);
         aiot_ra_setopt(ra_handle, AIOT_RAOPT_EVENT_HANDLER, (void *)ra_event_cb);
         for(int i = 0; i < sizeof(services) / sizeof(aiot_ra_service_t); i++) {
             aiot_ra_setopt(ra_handle, AIOT_RAOPT_ADD_SERVICE, (void *)&services[i]);
         }

   • Configuration item	Example	Description
     AIOT_RAOPT_MQTT_HANDLE	mqtt_handle	Requests for the remote logon feature are based on an MQTT connection. Use this configuration item to associate the MQTT connection handle.
     AIOT_RAOPT_NETWORK_CRED	cred	The security credential that the network uses when a remote logon connection is established.
     AIOT_RAOPT_EVENT_HANDLER	ra_event_cb	This callback function is triggered when the WebSocket status changes.
     AIOT_RAOPT_ADD_SERVICE	services[i]	The local services that the device supports when a remote logon connection is established.

2. 
   
   Important When you write the processing logic for the status monitoring callback function, do not call time-consuming or blocking functions.

   void ra_event_cb(void *handle, const aiot_ra_event_t *event, void *userdata)
   {
       switch(event->type)
       {
       case AIOT_RA_EVT_CONNECT:
           printf( "ra_event_cb AIOT_RA_EVT_CONNECT %s \r\n", event->tunnel_id);
           /* TODO: Notify that the WebSocket connection is established. Do not call time-consuming blocking functions here. */
           break;
       case AIOT_RA_EVT_DISCONNECT:
           printf( "ra_event_cb AIOT_RA_EVT_DISCONNECT %s \r\n", event->tunnel_id);
           /* TODO: Notify that the WebSocket connection is dropped. Do not call time-consuming blocking functions here. */
           break;
       case AIOT_RA_EVT_OPEN_WEBSOCKET:
           printf( "ra_event_cb AIOT_RA_EVT_OPEN_WEBSOCKET %s \r\n", event->tunnel_id);
           /* TODO: Notify that RA received the command to open the WebSocket connection. Do not call time-consuming blocking functions here. */
           break;
       case AIOT_RA_EVT_CLOSE_WEBSOCKET:
           printf( "ra_event_cb AIOT_RA_EVT_CLOSE_WEBSOCKET %s \r\n", event->tunnel_id);
           /* TODO: Notify that RA received the command to close the WebSocket connection. Do not call time-consuming blocking functions here. */
           break;
       }
   }

   
   
3. Define the types of locally supported remote services.
   Note The _SSH service is enabled by default. If this service is disabled, the remote logon feature is unavailable.

   aiot_ra_service_t services[] = {
       {
           .type = "_SSH",
           .ip = "127.0.0.1",
           .port = 22,
       },
   };

Step 3: Enable the remote logon channel

Call aiot_ra_start to send a request to IoT Platform. This request notifies IoT Platform that the device supports the remote logon feature.

    pthread_attr_t attr;
    pthread_attr_init(&attr);
    if (0 != pthread_create(&g_ra_process_thread, &attr, aiot_ra_start, (void*) ra_handle))
    {
        printf( "create remote_proxy_thread error!");
        return -1;
    }

Step 4: Enable remote logon

After IoT Platform receives the notification, you can enable remote logon to notify the device to open the connection channel. The device then connects to the remote channel of IoT Platform to establish a session and exchange messages.

You can enable remote logon in one of the following two ways:

• Enable remote logon in the console. For more information, see Remote logon.
• Enable remote logon from the device by calling the aiot_ra_request API:

  /**
   * @brief Actively requests to establish a channel.
   *
   * @param[in] handle A pointer to the RA session handle.
   *
   * @return int32_t*
   * @retval <STATE_SUCCESS The operation failed. For more information, see the definitions of STATE_REMOTE_*.
   * @retval >=STATE_SUCCESS The operation is successful.
   */
  int32_t  aiot_ra_request(void *handle);

Step 5: Close the remote logon channel

Call aiot_ra_stop to close the remote service channel.

    int i = 60000;
    while(1)
    {
        sleep(1);
        /* TODO: Business logic */
        i--;
        /*Set conditions based on your business logic. Call aiot_ra_stop to exit the thread.*/
        if(i == 0)
        {
            /*Exit the thread and close the RA service.*/
            aiot_ra_stop(ra_handle);
            break;
        }
    }

Step 6: Exit the program

Call aiot_ra_deinit to destroy the RA instance.

    aiot_ra_deinit(&ra_handle);