\section{rox\_\-soap.c File Reference}
\label{rox__soap_8c}\index{rox_soap.c@{rox\_\-soap.c}}
Interface to server programs using the SOAP protocol. 

{\tt \#include \char`\"{}rox-clib.h\char`\"{}}\par
{\tt \#include $<$stdlib.h$>$}\par
{\tt \#include $<$string.h$>$}\par
{\tt \#include $<$errno.h$>$}\par
{\tt \#include $<$ctype.h$>$}\par
{\tt \#include $<$signal.h$>$}\par
{\tt \#include $<$unistd.h$>$}\par
{\tt \#include $<$netdb.h$>$}\par
{\tt \#include $<$sys/types.h$>$}\par
{\tt \#include $<$sys/wait.h$>$}\par
{\tt \#include $<$glib.h$>$}\par
{\tt \#include $<$gdk/gdkx.h$>$}\par
{\tt \#include $<$X11/X.h$>$}\par
{\tt \#include $<$X11/Xatom.h$>$}\par
{\tt \#include $<$gtk/gtk.h$>$}\par
{\tt \#include $<$gtk/gtkinvisible.h$>$}\par
{\tt \#include $<$libxml/parser.h$>$}\par
{\tt \#include \char`\"{}rox\_\-soap.h\char`\"{}}\par
{\tt \#include \char`\"{}error.h\char`\"{}}\par
{\tt \#include \char`\"{}rox\_\-debug.h\char`\"{}}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct {\bf program}
\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef {\bf program} {\bf Program}
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void {\bf rox\_\-soap\_\-init} (void)
\item 
{\bf ROXSOAP} $\ast$ {\bf rox\_\-soap\_\-connect\_\-to\_\-filer} (void)
\item 
void {\bf rox\_\-soap\_\-close} ({\bf ROXSOAP} $\ast$con)
\item 
void {\bf rox\_\-soap\_\-define\_\-program} (const char $\ast$name, const char $\ast$atom\_\-format, const char $\ast$command)
\item 
char $\ast$ {\bf rox\_\-soap\_\-atom\_\-name\_\-for\_\-program} (const char $\ast$name)
\item 
xml\-Doc\-Ptr {\bf rox\_\-soap\_\-build\_\-xml} (const char $\ast$action, const char $\ast$ns\_\-url, xml\-Node\-Ptr $\ast$act)
\item 
gboolean {\bf rox\_\-soap\_\-send} ({\bf ROXSOAP} $\ast$prog, xml\-Doc\-Ptr doc, gboolean run\_\-prog, {\bf rox\_\-soap\_\-callback} callback, gpointer udata)
\item 
gboolean {\bf rox\_\-soap\_\-send\_\-via\_\-pipe} ({\bf ROXSOAP} $\ast$prog, xml\-Doc\-Ptr doc, {\bf rox\_\-soap\_\-callback} callback, gpointer udata)
\item 
void {\bf rox\_\-soap\_\-set\_\-timeout} ({\bf ROXSOAP} $\ast$prog, guint ms)
\item 
const char $\ast$ {\bf rox\_\-soap\_\-get\_\-last\_\-error} (void)
\item 
void {\bf rox\_\-soap\_\-clear\_\-error} (void)
\end{CompactItemize}


\subsection{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.

\begin{Desc}
\item[Author:]Thomas Leonard, Stephen Watson \end{Desc}
\begin{Desc}
\item[Version:]\begin{Desc}
\item[Id]\doxyref{rox\_\-soap.c}{p.}{rox__soap_8c},v 1.17 2006/08/12 17:04:56 stephen Exp \end{Desc}
\end{Desc}


\subsection{Typedef Documentation}
\index{rox_soap.c@{rox\_\-soap.c}!Program@{Program}}
\index{Program@{Program}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct {\bf program}  {\bf Program}}\label{rox__soap_8c_7da92d396a59e796c929b1f1510b8342}


Definition of how we contact a program. 

\subsection{Function Documentation}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_atom_name_for_program@{rox\_\-soap\_\-atom\_\-name\_\-for\_\-program}}
\index{rox_soap_atom_name_for_program@{rox\_\-soap\_\-atom\_\-name\_\-for\_\-program}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ rox\_\-soap\_\-atom\_\-name\_\-for\_\-program (const char $\ast$ {\em name})}\label{rox__soap_8c_0a1611664e879cdeef57a2311516899c}


Returns the name of the atom which will be used to locate the given program. It uses the format given in the \doxyref{rox\_\-soap\_\-define\_\-program()}{p.}{rox__soap_8c_136c11a5cbf6d9cf9de5d5d233dd3b47} call, with the defined substitutions.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em name}]name of program \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]atom name to use (pass to g\_\-free() when done) or {\tt NULL} if the program is not known. \end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_build_xml@{rox\_\-soap\_\-build\_\-xml}}
\index{rox_soap_build_xml@{rox\_\-soap\_\-build\_\-xml}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}xml\-Doc\-Ptr rox\_\-soap\_\-build\_\-xml (const char $\ast$ {\em action}, const char $\ast$ {\em ns\_\-url}, xml\-Node\-Ptr $\ast$ {\em act})}\label{rox__soap_8c_c6e389e89e70fb751d5c26e811c7afb6}


Build part of XML document to send. The action to perform is in name space {\em ns\_\-url\/}. Add arguments to the node {\em act\/}, then call \doxyref{rox\_\-soap\_\-send()}{p.}{rox__soap_8c_9740068829b6e524f529b81a2ba5b089} with the return value.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em action}]Action to perform, the name of the element in the SOAP body. \item[\mbox{$\leftarrow$} {\em ns\_\-url}]name space of the program \item[\mbox{$\rightarrow$} {\em act}]XML node, with name {\em action\/}, where arguments may be added \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]XML document defining the SOAP message to send. \end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_clear_error@{rox\_\-soap\_\-clear\_\-error}}
\index{rox_soap_clear_error@{rox\_\-soap\_\-clear\_\-error}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-soap\_\-clear\_\-error (void)}\label{rox__soap_8c_225727696f2e260a1c34d86ccbbcbb44}


Clear last error \begin{Desc}
\item[{\bf Deprecated}]use \doxyref{rox\_\-error\_\-queue\_\-flush()}{p.}{error_8c_ab97b7230e9447838764592eaa23d6c3} instead. \end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_close@{rox\_\-soap\_\-close}}
\index{rox_soap_close@{rox\_\-soap\_\-close}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-soap\_\-close ({\bf ROXSOAP} $\ast$ {\em con})}\label{rox__soap_8c_ea346dc1dda7f8d5865ff5d371153c77}


Close connection to a SOAP server. \index{rox_soap.c@{rox\_\-soap.c}!rox_soap_connect_to_filer@{rox\_\-soap\_\-connect\_\-to\_\-filer}}
\index{rox_soap_connect_to_filer@{rox\_\-soap\_\-connect\_\-to\_\-filer}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf ROXSOAP}$\ast$ rox\_\-soap\_\-connect\_\-to\_\-filer (void)}\label{rox__soap_8c_c549c4215e90929162a0964f98db410c}


Open connection to ROX-Filer.

\begin{Desc}
\item[Returns:]connection to ROX-Filer. \end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_define_program@{rox\_\-soap\_\-define\_\-program}}
\index{rox_soap_define_program@{rox\_\-soap\_\-define\_\-program}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-soap\_\-define\_\-program (const char $\ast$ {\em name}, const char $\ast$ {\em atom\_\-format}, const char $\ast$ {\em command})}\label{rox__soap_8c_136c11a5cbf6d9cf9de5d5d233dd3b47}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em name}]name of program as passed to rox\_\-soap\_\-connect(). \item[\mbox{$\leftarrow$} {\em atom\_\-format}]format of atom name to use to connect, e is effective UID, h is fully qualified domain name (FQDN) of display \item[\mbox{$\leftarrow$} {\em command}]command that may be fed the SOAP document on stdin if connecting via the atom fails, may be {\tt NULL} \end{description}
\end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_get_last_error@{rox\_\-soap\_\-get\_\-last\_\-error}}
\index{rox_soap_get_last_error@{rox\_\-soap\_\-get\_\-last\_\-error}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ rox\_\-soap\_\-get\_\-last\_\-error (void)}\label{rox__soap_8c_5800d151117aef959e01956e0d23d6e6}


\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{rox\_\-error\_\-queue\_\-fetch()}{p.}{error_8c_7b3398cb928056d538e83862cc93b8d0} instead. \begin{Desc}
\item[Returns:]text message of last error \end{Desc}
\end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_init@{rox\_\-soap\_\-init}}
\index{rox_soap_init@{rox\_\-soap\_\-init}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-soap\_\-init (void)}\label{rox__soap_8c_6eb8069e937ba6535dc72745432b85a2}


Initialize the SOAP system. \index{rox_soap.c@{rox\_\-soap.c}!rox_soap_send@{rox\_\-soap\_\-send}}
\index{rox_soap_send@{rox\_\-soap\_\-send}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}gboolean rox\_\-soap\_\-send ({\bf ROXSOAP} $\ast$ {\em prog}, xml\-Doc\-Ptr {\em doc}, gboolean {\em run\_\-prog}, {\bf rox\_\-soap\_\-callback} {\em callback}, gpointer {\em udata})}\label{rox__soap_8c_9740068829b6e524f529b81a2ba5b089}


Send the XML document to a program using SOAP. If {\em run\_\-prog\/} is {\tt TRUE} and there is no program to talk to, use \doxyref{rox\_\-soap\_\-send\_\-via\_\-pipe()}{p.}{rox__soap_8c_c7992c719986a9a165ef643345444326}. When complete callback is called with the status and reply.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em prog}]connection to program \item[\mbox{$\leftarrow$} {\em doc}]XML document containg SOAP message \item[\mbox{$\leftarrow$} {\em run\_\-prog}]if {\tt FALSE} and the program could not be contacted, then return failure. Otherwise if a command has been defined (see \doxyref{rox\_\-soap\_\-define\_\-program()}{p.}{rox__soap_8c_136c11a5cbf6d9cf9de5d5d233dd3b47}) execute that and send {\em doc\/} to its standard input and read back the reply from its standard output. \item[\mbox{$\leftarrow$} {\em callback}]function to call after contact has been made and the server returns success or failure. \item[\mbox{$\leftarrow$} {\em udata}]addtional data to pass to {\em callback\/}. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]{\tt FALSE} if the call failed, see \doxyref{rox\_\-soap\_\-get\_\-last\_\-error()}{p.}{rox__soap_8c_5800d151117aef959e01956e0d23d6e6}. \end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_send_via_pipe@{rox\_\-soap\_\-send\_\-via\_\-pipe}}
\index{rox_soap_send_via_pipe@{rox\_\-soap\_\-send\_\-via\_\-pipe}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}gboolean rox\_\-soap\_\-send\_\-via\_\-pipe ({\bf ROXSOAP} $\ast$ {\em prog}, xml\-Doc\-Ptr {\em doc}, {\bf rox\_\-soap\_\-callback} {\em callback}, gpointer {\em udata})}\label{rox__soap_8c_c7992c719986a9a165ef643345444326}


Send the XML document to a program using SOAP by executing the defined program, sending {\em 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.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftarrow$} {\em prog}]connection to program \item[\mbox{$\leftarrow$} {\em doc}]XML document containg SOAP message \item[\mbox{$\leftarrow$} {\em callback}]function to call after contact has been made and the server returns success or failure. \item[\mbox{$\leftarrow$} {\em udata}]addtional data to pass to {\em callback\/}. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]{\tt FALSE} if the call failed, see \doxyref{rox\_\-soap\_\-get\_\-last\_\-error()}{p.}{rox__soap_8c_5800d151117aef959e01956e0d23d6e6}. \end{Desc}
\index{rox_soap.c@{rox\_\-soap.c}!rox_soap_set_timeout@{rox\_\-soap\_\-set\_\-timeout}}
\index{rox_soap_set_timeout@{rox\_\-soap\_\-set\_\-timeout}!rox_soap.c@{rox\_\-soap.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void rox\_\-soap\_\-set\_\-timeout ({\bf ROXSOAP} $\ast$ {\em prog}, guint {\em ms})}\label{rox__soap_8c_bc0d7093cf07bf537aabd3e03f2cfcdb}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[\mbox{$\leftrightarrow$} {\em prog}]program to set time out for, or {\tt NULL} to set default time out for all subsequent programs. \item[\mbox{$\leftarrow$} {\em ms}]time out in milliseconds \end{description}
\end{Desc}
