Bindings

This document describes how to create a program interracting with Pyrame modules.

The Pyrame binding API

In order to make Pyrame easy to interact with, we provide bindings for numerous languages. These bindings are 5 simple functions that implement the Pyrame protocol:

• open_socket(host,port)
• get_port(name)
• execcmd(sock,name,*args)
• sendcmd(host,port,name,*args)

open_socket

The open_socket function opens a TCP socket that is usable with Pyrame. It takes two arguments:

• the host: the IP address or the DNS name of the machine where the module you need is running.
• the port: the TCP port on which the module is listening

It returns the socket file descriptor

get_port

The get_port function searches a port name. It takes one argument:

• the name of the port as a string

It returns the number of the port

execcmd

The execcmd function executes a Pyrame command on a module through a given socket. It takes a variable number of arguments:

• a socket (as returned by the open_socket function)
• the name of the function we want to execute on the module
• a variable number of arguments depending on the function

it returns the boolean return value and the return string value of the command

sendcmd

The sendcmd function is very similar to the execcmd function. The difference is that it opens the socket itself. It takes a variable number of arguments:

• the host: the IP address or the DNS name of the machine where the module you need is running.
• the port: the TCP port on which the module is listening
• the name of the function we want to execute on the module
• a variable number of arguments depending on the function

it returns the boolean return value and the return string value of the command

The advantage of execcmd over sendcmd is that when using the former, the same socket can be reused several times, reducing the system time needed for each command.

An example in Python

In this example, we get the port of our module and we send it a helloworld_test command.

Here is the code:

#!/usr/bin/env python2
import bindpyrame
import socket,sys

#find the test port
port = bindpyrame.get_port("TEST_PORT")

#open a socket and send the command
sockid = bindpyrame.open_socket("localhost",port)
retcode,res=bindpyrame.execcmd(sockid,"helloworld_test","")

#print the result
print("execcmd: retcode=%d res=%s"%(retcode,res))

The execcmd section can be replaced by its sendcmd equivalent:

retcode,res=bindpyrame.sendcmd("localhost",port,"helloworld_test","")

The example in C or C++

Here is the equivalent code in C or C++:

#include <pyrame.h>
int main() {
  struct cmd_result *result;
  int port;

  //find the test port
  port = get_port("TEST_PORT");

  //open a socket and send the command
  result = sendcmd("localhost",port,"helloworld_test","","end");

  //print the result
  printf("sendcmd: retcode=%d res=%s\n",result->retcode,result->str);
  free(result->str);
  free(result);

Pay attention to the “end” parameter in sendcmd and execcmd that marks the end of the variable number of parameters. Forgetting it can produce segmentation faults. To be compact, this code has been written without any check but in a real application they should be implemented.