<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id$ -->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
	<!ENTITY firstname "Pierre">
	<!ENTITY surname   "Pronchery">
	<!ENTITY username  "khorben">
	<!ENTITY email     "khorben@defora.org">
	<!ENTITY section   "1">
	<!ENTITY title     "libApp User Manual">
	<!ENTITY package   "DeforaOS libApp">
	<!ENTITY name      "AppBroker">
	<!ENTITY purpose   "Broker for the App message-passing specification">
]>
<refentry>
	<refentryinfo>
		<title>&title;</title>
		<productname>&package;</productname>
		<authorgroup>
			<author>
				<firstname>&firstname;</firstname>
				<surname>&surname;</surname>
				<contrib>Code and documentation.</contrib>
				<address>
					<email>&email;</email>
				</address>
			</author>
		</authorgroup>
		<copyright>
			<year>2014</year>
			<holder>&firstname; &surname; &lt;&email;&gt;</holder>
		</copyright>
		<legalnotice>
			<para>This manual page was written for the DeforaOS project (and may be
				used by others).</para>
			<para>Permission is granted to copy, distribute and/or modify this
				document under the terms of the GNU General Public License,
				Version 3 as published by the Free Software Foundation.</para>
		</legalnotice>
	</refentryinfo>
	<refmeta>
		<refentrytitle>&name;</refentrytitle>
		<manvolnum>&section;</manvolnum>
	</refmeta>
	<refnamediv>
		<refname>&name;</refname>
		<refpurpose>&purpose;</refpurpose>
	</refnamediv>
	<refsynopsisdiv>
		<cmdsynopsis>
			<command>&name;</command>
			<group>
				<arg choice="plain"><option>-c</option></arg>
				<arg choice="plain"><option>-s</option></arg>
			</group>
			<arg choice="opt"><option>-o</option>
				<replaceable>output</replaceable></arg>
			<arg choice="plain"><replaceable>filename</replaceable></arg>
		</cmdsynopsis>
	</refsynopsisdiv>
	<refsect1 id="description">
		<title>Description</title>
		<para><command>&name;</command> is a broker for the App message-passing
			protocol. It translates an interface definition file into a C header file,
		suitable as a reference while implementing an AppServer.</para>
	</refsect1>
	<refsect1 id="options">
		<title>Options</title>
		<para>&name; expects a specification file to be specified on the command line.
			The following options are available:</para>
		<variablelist>
			<varlistentry>
				<term><option>-c</option></term>
				<listitem>
					<para>Generate a file suitable for a client.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-s</option></term>
				<listitem>
					<para>Generate a file suitable for a server. This is the default
						behavior.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-o</option></term>
				<listitem>
					<para>Output file.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</refsect1>
	<refsect1 id="example">
		<title>Example</title>
		<para>The following interface definition file:</para>
		<programlisting>service=VFS

[call::chmod]
ret=INT32
arg1=STRING,pathname
arg2=UINT32,mode</programlisting>
		<para>will likely be translated as follows for a server:</para>
		<programlisting>/* $Id$ */



#ifndef VFS_VFS_H
# define VFS_VFS_H

# include &lt;stdint.h&gt;
# include &lt;System/App.h&gt;


/* types */
typedef Buffer * BUFFER;
typedef double * DOUBLE;
typedef float * FLOAT;
typedef int16_t INT16;
typedef int32_t INT32;
typedef uint16_t UINT16;
typedef uint32_t UINT32;
typedef String const * STRING;
typedef void VOID;

typedef BUFFER BUFFER_IN;

typedef DOUBLE DOUBLE_IN;

typedef FLOAT FLOAT_IN;
typedef INT32 INT32_IN;
typedef UINT32 UINT32_IN;
typedef STRING STRING_IN;

typedef Buffer * BUFFER_OUT;
typedef int32_t * INT32_OUT;
typedef uint32_t * UINT32_OUT;
typedef String ** STRING_OUT;

typedef Buffer * BUFFER_INOUT;
typedef int32_t * INT32_INOUT;
typedef uint32_t * UINT32_INOUT;
typedef String ** STRING_INOUT;


/* calls */
INT32 VFS_chmod(App * app, AppServerClient * client, STRING pathname, UINT32 mode);

#endif /* !VFS_VFS_H */</programlisting>
	</refsect1>
	<refsect1 id="bugs">
		<title>Bugs</title>
		<para>Issues can be listed and reported at <ulink
				url="http://www.defora.org/os/project/bug_list/3564/libApp"/>.</para>
	</refsect1>
	<refsect1 id="see_also">
		<title>See also</title>
		<para>
			<citerefentry>
				<refentrytitle>AppClient</refentrytitle>
				<manvolnum>1</manvolnum>
			</citerefentry>
		</para>
	</refsect1>
</refentry>
<!-- vim: set noet ts=1 sw=1 sts=1 tw=80: -->
