[Documentation] [TitleIndex] [WordIndex

Only released in EOL distros:  

librms: rmscpp

Package Summary

Client library for the RMS API written in C++.

About

The rmscpp package is a client library, written in C++, for the rms (Robot Management System) REST API. This library allows for external programs to interact with the RMS MySQL database. By doing so, we are able to do things like parse log data from user studies externally, or write ROS nodes which retrieve, add, or modify data within the RMS system itself.

Installation

To install the librms stack, you can choose to either install from source, or from the Ubuntu package:

Source

To install from source, execute the following:

Ubuntu Package

To install the Ubuntu package, execute the following:

Library Example

In the following example, we will make both an unauthenticated call, and an authenticated call to the RMS API. This tutorial assumes that you have installed the RMS locally; however, it can be easily adapted to access a remote server.

The C++ Code

   1 /*
   2  * A simple example that utilizes the RMS library from the rmscpp package.
   3  *
   4  * Author: Russell Toris - rctoris@wpi.edu
   5  *
   6  * Version: November 15, 2012
   7  */
   8 
   9 #include <iostream>
  10 #include <rmscpp/rms.h>
  11 
  12 using namespace std;
  13 using namespace rms;
  14 
  15 int main(int argc, char **argv)
  16 {
  17   // create a connection to the RMS
  18   rms_client client("localhost");
  19 
  20   // first, let's count the number of articles per page
  21   vector<content_page> pages = client.get_content_pages();
  22   for (uint i = 0; i < pages.size(); i++)
  23   {
  24     // grab the articles for this page
  25     int pageid = pages.at(i).get_pageid();
  26     vector<article> articles = client.get_articles_by_pageid(pageid);
  27 
  28     // notify us of how many articles we found
  29     string title = pages.at(i).get_title();
  30     cout << "Content Page \"" << title << "\" has " 
  31            << articles.size() << " article(s)." << endl;
  32   }
  33 
  34   // now let's try and make a call we do not have permission to make yet
  35   try
  36   {
  37     client.get_user_accounts();
  38   }
  39   catch (string &error)
  40   {
  41     cerr << endl << "ERROR: " << error << endl;
  42   }
  43 
  44   // if we authenticate, we will be able to make the call successfully
  45   client.set_authorization("admin", "myremotelab");
  46   vector<user_account> users = client.get_user_accounts();
  47   cout << endl << "There are " << users.size() << " user(s)." << endl;
  48 }

Code Explanation

Now that we have a running example, let's look at each piece.

  10 #include <rmscpp/rms.h>
  11 

In order to utilize the RMS library, we must import the single client header file. We also include the iostream header to allow for terminal printing.

  17   // create a connection to the RMS
  18   rms_client client("localhost");

We start by creating a client object that will connect to localhost using the default parameters (i.e., port 80, and using HTTP).

  20   // first, let's count the number of articles per page
  21   vector<content_page> pages = client.get_content_pages();
  22   for (uint i = 0; i < pages.size(); i++)
  23   {
  24     // grab the articles for this page
  25     int pageid = pages.at(i).get_pageid();
  26     vector<article> articles = client.get_articles_by_pageid(pageid);
  27 
  28     // notify us of how many articles we found
  29     string title = pages.at(i).get_title();
  30     cout << "Content Page \"" << title << "\" has " 
  31            << articles.size() << " article(s)." << endl;
  32   }

First, we will make a call that requires no authentication. This basic example will grab a list of all content pages in the RMS, and then count the number of articles that were found for that given page. This information is printed to the terminal.

  34   // now let's try and make a call we do not have permission to make yet
  35   try
  36   {
  37     client.get_user_accounts();
  38   }
  39   catch (string &error)
  40   {
  41     cerr << endl << "ERROR: " << error << endl;
  42   }

Next, we attempt to grab a list of all of the user accounts. This call requires an admin to be authenticated. To illustrate what will happen if you do not authenticate, we surround the call in a try-catch block. The error string that is reported is the one that comes from the API.

  44   // if we authenticate, we will be able to make the call successfully
  45   client.set_authorization("admin", "myremotelab");
  46   vector<user_account> users = client.get_user_accounts();
  47   cout << endl << "There are " << users.size() << " user(s)." << endl;

Finally, we authenticate (using the default admin password supplied with the base install of RMS), and make the call again. We then report the number of users found in the system.

Support

Please send bug reports to the GitHub Issue Tracker. Feel free to contact me at any point with questions and comments.


wpi.png

rail.png


2023-10-28 12:57