======== 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 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.