ROX-CLib: rox_soap.c File Reference

- Main Page
- Data Structures
- Files
- Related Pages

- File List
- Globals

# rox_soap.c File Reference

Interface to server programs using the SOAP protocol. More...

`#include "rox-clib.h"`
`#include <stdlib.h>`
`#include <string.h>`
`#include <errno.h>`
`#include <ctype.h>`
`#include <signal.h>`
`#include <unistd.h>`
`#include <netdb.h>`
`#include <sys/types.h>`
`#include <sys/wait.h>`
`#include <glib.h>`
`#include <gdk/gdkx.h>`
`#include <X11/X.h>`
`#include <X11/Xatom.h>`
`#include <gtk/gtk.h>`
`#include <gtk/gtkinvisible.h>`
`#include <libxml/parser.h>`
`#include "rox_soap.h"`
`#include "error.h"`
`#include "rox_debug.h"`

## Data Structures
struct | program
## Typedefs
typedef program | Program
## Functions
void | rox_soap_init (void)
ROXSOAP * | rox_soap_connect_to_filer (void)
void | rox_soap_close (ROXSOAP *con)
void | rox_soap_define_program (const char *name, const char *atom_format, const char *command)
char * | rox_soap_atom_name_for_program (const char *name)
xmlDocPtr | rox_soap_build_xml (const char *action, const char *ns_url, xmlNodePtr *act)
gboolean | rox_soap_send (ROXSOAP *prog, xmlDocPtr doc, gboolean run_prog, rox_soap_callback callback, gpointer udata)
gboolean | rox_soap_send_via_pipe (ROXSOAP *prog, xmlDocPtr doc, rox_soap_callback callback, gpointer udata)
void | rox_soap_set_timeout (ROXSOAP *prog, guint ms)
const char * | rox_soap_get_last_error (void)
void | rox_soap_clear_error (void)

## Detailed Description

Interface to server programs using the SOAP protocol.

SOAP allows you to communicate with server programs via the X server. You may implement your applications to function from a single instance no matter how many times they are started, much as ROX-Filer does itself.

Author:
  Thomas Leonard, Stephen Watson

Version:
  Id
    rox_soap.c,v 1.17 2006/08/12 17:04:56 stephen Exp

## Typedef Documentation

typedef struct program Program

Definition of how we contact a program.

## Function Documentation

char* rox_soap_atom_name_for_program | ( | const char * | name | ) |

Returns the name of the atom which will be used to locate the given program. It uses the format given in the rox_soap_define_program() call, with the defined substitutions.

Parameters:

  `[in]` | name | name of program

Returns:
  atom name to use (pass to g_free() when done) or `NULL` if the program is not known.

xmlDocPtr rox_soap_build_xml | ( | const char * | action,
|  | const char * | ns_url,
|  | xmlNodePtr * | act |
| ) |  |  |

Build part of XML document to send. The action to perform is in name space ns_url. Add arguments to the node act, then call rox_soap_send() with the return value.

Parameters:

  `[in]` | action | Action to perform, the name of the element in the SOAP body.
  `[in]` | ns_url | name space of the program
  `[out]` | act | XML node, with name action, where arguments may be added

Returns:
  XML document defining the SOAP message to send.

void rox_soap_clear_error | ( | void |  | ) |

Clear last error

Deprecated:
  use rox_error_queue_flush() instead.

void rox_soap_close | ( | ROXSOAP * | con | ) |

Close connection to a SOAP server.

ROXSOAP* rox_soap_connect_to_filer | ( | void |  | ) |

Open connection to ROX-Filer.

Returns:
  connection to ROX-Filer.

void rox_soap_define_program | ( | const char * | name,
|  | const char * | atom_format,
|  | const char * | command |
| ) |  |  |

Define how to connect to the named program. An entry for ROX-Filer is pre-defined.

Parameters:

  `[in]` | name | name of program as passed to rox_soap_connect().
  `[in]` | atom_format | format of atom name to use to connect, e is effective UID, h is fully qualified domain name (FQDN) of display
  `[in]` | command | command that may be fed the SOAP document on stdin if connecting via the atom fails, may be `NULL`

const char* rox_soap_get_last_error | ( | void |  | ) |

Deprecated:
  use rox_error_queue_fetch() instead.
  Returns:
    text message of last error

void rox_soap_init | ( | void |  | ) |

Initialize the SOAP system.

gboolean rox_soap_send | ( | ROXSOAP * | prog,
|  | xmlDocPtr | doc,
|  | gboolean | run_prog,
|  | rox_soap_callback | callback,
|  | gpointer | udata |
| ) |  |  |

Send the XML document to a program using SOAP. If run_prog is `TRUE` and there is no program to talk to, use rox_soap_send_via_pipe(). When complete callback is called with the status and reply.

Parameters:

  `[in]` | prog | connection to program
  `[in]` | doc | XML document containg SOAP message
  `[in]` | run_prog | if `FALSE` and the program could not be contacted, then return failure. Otherwise if a command has been defined (see rox_soap_define_program()) execute that and send doc to its standard input and read back the reply from its standard output.
  `[in]` | callback | function to call after contact has been made and the server returns success or failure.
  `[in]` | udata | addtional data to pass to callback.

Returns:
  `FALSE` if the call failed, see rox_soap_get_last_error().

gboolean rox_soap_send_via_pipe | ( | ROXSOAP * | prog,
|  | xmlDocPtr | doc,
|  | rox_soap_callback | callback,
|  | gpointer | udata |
| ) |  |  |

Send the XML document to a program using SOAP by executing the defined program, sending doc to its standard input and reading back the reply from its standard output. If no command has been defined for the program then the call fails.

When complete callback is called with the status and reply.

Parameters:

  `[in]` | prog | connection to program
  `[in]` | doc | XML document containg SOAP message
  `[in]` | callback | function to call after contact has been made and the server returns success or failure.
  `[in]` | udata | addtional data to pass to callback.

Returns:
  `FALSE` if the call failed, see rox_soap_get_last_error().

void rox_soap_set_timeout | ( | ROXSOAP * | prog,
|  | guint | ms |
| ) |  |  |

Set the time to wait for a reply from a SOAP call.

Parameters:

  `[in,out]` | prog | program to set time out for, or `NULL` to set default time out for all subsequent programs.
  `[in]` | ms | time out in milliseconds