/usr/share/doc/libxr1-dev/html/howto.html is in libxr1-dev 1.0-2.1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-2">
<title>HOWTO</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<style>
h1, h2 {
text-align: left;
}
body {
margin-top: 6ex;
margin-bottom: 6ex;
}
#topbar {
position: fixed;
top: 0;
left: 0;
height: 3ex;
margin: 0;
padding: 1ex;
background-color: #e8eef2;
border-bottom: 1px solid #84B0C7;
width: 100%;
}
#topbar a {
font-size: 140%;
font-weight: bold;
color: darkred;
}
#topbar a:visited {
font-size: 140%;
font-weight: bold;
color: darkred;
}
#botbar {
position: fixed;
bottom: 0;
left: 0;
height: 3ex;
margin: 0;
padding: 1ex;
background-color: #e8eef2;
border-top: 1px solid #84B0C7;
width: 100%;
text-align: center;
}
hr {
border-top: 1px solid #84B0C7;
height: 1px;
}
</style>
</head><body>
<div id="topbar">
<a href="index.html">libxr</a> — <span>developer's documentation</span>
</div>
<!-- Generated by Doxygen 1.8.6 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">HOWTO </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This HOWTO shows how to implement XML-RPC server and client in C using libxr.</p>
<p>As an example we will implement simple remote management interface for Zblok.</p>
<p>Interface specification:</p>
<ul>
<li>Client must authenticate against zblok users database. </li>
<li>Client should be allowed to read status information about zblok. </li>
<li>Client should be able to change his/her password.</li>
</ul>
<h1><a class="anchor" id="Server"></a>
Server</h1>
<p>Server interface is implemented using so called servlet. Servlet is an object on the server that has constructor, destructor and implements interface methods.</p>
<p>When client connects to the server, server creates <a class="el" href="xr-server_8h_ae74fd15c851ccb6f49c1eba0707b6c0b.html#ae74fd15c851ccb6f49c1eba0707b6c0b">xr_servlet</a> and waits for RPCs. On the first RPC, servlet is looked up in the list of registered servlets by the resource passed in the HTTP header and constructor is called.</p>
<p>Server interface can be described using <a class="el" href="xdl.html">XDL Language</a>. You can put implementation code of servlet directly into XDL file. Following XDL code describes interface of our Zblok management server.</p>
<div class="fragment"><div class="line"><span class="keyword">namespace </span>ZM; <span class="comment">// Zblok Management</span></div>
<div class="line"></div>
<div class="line"><span class="comment">// interface error codes</span></div>
<div class="line">error AUTH_FAILED = 1;</div>
<div class="line">error NOT_AUTHORIZED = 2;</div>
<div class="line"></div>
<div class="line"><span class="comment">// structure describing zblok user state</span></div>
<div class="line"><span class="keyword">struct </span>User</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">string</span> username;</div>
<div class="line"> <span class="keywordtype">string</span> realname;</div>
<div class="line"> <span class="keywordtype">int</span> mail_usage;</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">// structure describing zblok folder state</span></div>
<div class="line"><span class="keyword">struct </span>Folder</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">string</span> name;</div>
<div class="line"> <span class="keywordtype">string</span> type;</div>
<div class="line"> <span class="keywordtype">int</span> size;</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">// system status, combines previous two structures</span></div>
<div class="line"><span class="keyword">struct </span>SystemStatus</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> uptime;</div>
<div class="line"> array<User> users;</div>
<div class="line"> array<Folder> folders;</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line">servlet Server</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">boolean</span> auth (<span class="keywordtype">string</span> username, </div>
<div class="line"> <span class="keywordtype">string</span> password);</div>
<div class="line"> SystemStatus getSystemStatus ();</div>
<div class="line"> <span class="keywordtype">boolean</span> changeUserPassword (<span class="keywordtype">string</span> newpassword);</div>
<div class="line">}</div>
</div><!-- fragment --><p>Now we will use <a class="el" href="xdlc.html">XDL Language Compiler</a> to compile this XDL file into C source code that implements client and server interfaces and stubs for implementation of servlet methods.</p>
<pre class="fragment">xdl-compiler -i zblok.xdl -o .
</pre><p>This command should create following files in the current directory:</p>
<pre class="fragment">.
|-- ZMCommon.c
|-- ZMCommon.h
|-- ZMCommon.xrm.h
|-- ZMServer.c
|-- ZMServer.h
|-- ZMServer.stubs.c
|-- ZMServer.stubs.h
|-- ZMServer.xrc.c
|-- ZMServer.xrc.h
|-- ZMServer.xrm.h
|-- ZMServer.xrs.c
`-- ZMServer.xrs.h
</pre><p>You can inspect these files to see how things are implemented, but it is not necessary. The most interesting file is ZMServer.stubs.c which implements servlet methods.</p>
<p>Next step is implementation of servlet methods in the XDL file:</p>
<div class="fragment"></div><!-- fragment --><p>Now that we have implemented servlet methods, we must create server. Libxr offers multiple ways to implement server. The simplest way is this:</p>
<div class="fragment"></div><!-- fragment --><p>That's it! Server is done, now we have to compile it:</p>
<pre class="fragment">gcc -o zm-server server.c ZMCommon.c ZMServer.c ZMServer.stubs.c \
ZMServer.xrs.c `pkg-config --cflags --libs libxr` -lssl -lcrypto
</pre><h1><a class="anchor" id="Client"></a>
Client</h1>
<p>Ok, now we have server and we want to connect to it so we need to implement client. Following code will connect to the server, authenticates user and changes his password:</p>
<div class="fragment"></div><!-- fragment --><p>You can compile client code using:</p>
<pre class="fragment">gcc -o zm-client client.c ZMCommon.c ZMServer.c ZMServer.xrc.c \
`pkg-config --cflags --libs libxr` -lssl -lcrypto
</pre><p>And that's it. </p>
</div></div><!-- contents -->
<div id="botbar">
Documentation for <a style="color:darkred;" href="index.html">libxr</a>, Mon Jan 6 2014 07:32:37.
</div>
</body>
</html>
|