added introduction and example documentation

diff --git a/.gitignore b/.gitignore
index 5aa623f..878a53f 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -34,3 +34,20 @@ test/data/test-gumd-dbus.conf
 examples/gum-example
 stamp-h1
 *service
+docs/gumd-decl-list.txt
+docs/gumd-decl.txt
+docs/gumd-overrides.txt
+docs/gumd-sections.txt
+docs/gumd-undeclared.txt
+docs/gumd-undocumented.txt
+docs/gumd-unused.txt
+docs/gumd.args
+docs/gumd.hierarchy
+docs/gumd.interfaces
+docs/gumd.prerequisites
+docs/gumd.signals
+docs/gumd.types
+docs/html/
+docs/version.xml
+docs/xml/
+

diff --git a/docs/building.xml b/docs/building.xml
index 0569f22..ef0fde1 100644 (file)
--- a/docs/building.xml
+++ b/docs/building.xml
@@ -4,9 +4,7 @@
 ]>
 <refentry id="um-building">
   <refmeta>
-    <refentrytitle>Building and installing the user management daemon (gumd)
-        and client library (libgum).
-    </refentrytitle>
+    <refentrytitle>Building and Installation</refentrytitle>
     <manvolnum>3</manvolnum>
     <refmiscinfo>Gumd</refmiscinfo>
   </refmeta>

diff --git a/docs/examples.xml b/docs/examples.xml
index 8ff15e2..38468b6 100644 (file)
--- a/docs/examples.xml
+++ b/docs/examples.xml
@@ -4,159 +4,224 @@
 ]>
 <refentry id="gumd-examples">
   <refmeta>
-    <refentrytitle>gumd usage examples</refentrytitle>
+    <refentrytitle>Examples</refentrytitle>
   </refmeta>
 
   <refsect1 id="intro">
     <title>Introduction</title>
     <para>
-        libgsignond-glib comes with an example application <application>gsso-example</application>
-        that demonstrates the most common use cases: listing available authentication methods and
-        their mechanisms, creating and removing identities and performing authentication
-        sessions.
+        libgum comes with an example application
+        <application>gum-example</application> that demonstrates the most
+        common use cases: creating users/groups, deleting users/groups,
+        modifying users/groups, and querying users/groups
     </para>
     <para>
-        Before running the example application, make sure that gSSO daemon and
-        gSSO UI (that is appropriate for your system) are installed and configured
-        correctly.
+        Before running the example application, make sure that gum daemon and
+        libgum are installed and configured correctly.
     </para>
     <para>
         The source code for the example application is available at
-        <ulink url="http://code.google.com/p/accounts-sso/source/browse/examples/gsso-example.c?repo=libgsignon-glib&amp;name=master">
-            http://code.google.com/p/accounts-sso/source/browse/examples/gsso-example.c?repo=libgsignon-glib&amp;name=master</ulink>
+        <ulink url="https://github.com/01org/gumd/blob/master/examples/gum-example.c">
+           gum-example</ulink>
      </para>
      <para>
-         The full list of available <application>gsso-example</application> options can be 
-         obtained with <userinput>gsso-example --help-all</userinput>
+         The full list of available <application>gum-example</application>
+         options can be obtained with
+         <userinput>gum-example --help-all</userinput>
      </para>
   </refsect1>
          
   <refsect1>
-    <title>Authentication methods and mechanisms</title>
+    <title>Add User</title>
     <para>
-        The list of available authentication methods can be obtained with
-        <userinput>--query-methods</userinput>:
-        <literallayout><computeroutput>
-<userinput>> gsso-example --query-methods</userinput>:
-Available authentication methods:
-        password
-        oauth
-        digest
-        </computeroutput></literallayout>
-     </para>
-     <para>
-         For each of the available authentication methods it's possible to query
-         available authentication mechanisms with 
-         <userinput>gsso-example --query-mechanisms=method</userinput>:
-        <literallayout><computeroutput>
-<userinput>> gsso-example --query-mechanisms=oauth</userinput>
-Available authentication mechanisms for method oauth:
-        oauth1
-        oauth2
-        </computeroutput></literallayout>
-     </para>
-         
+        User can be added with flag <userinput>--add-user</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --add-user &lt;mandatory-args&gt; &lt;optional-args&gt;</userinput>:
+                    mandatory-args are:
+                        --username=&lt;username&gt; OR --nickname=&lt;nickname&gt;
+                        --usertype=&lt;usertype&gt;
+                         possible usertypes are: system(1), admin(2), guest(3), normal(4).
+                    optional-args are:
+                        --usecret=&lt;secret&gt;
+                        --realname=&lt;realname&gt;
+                        --office=&lt;office location&gt;
+                        --officephone=&lt;ooffice phone&gt;
+                        --homephone=&lt;home phone&gt;
+                        --homedir=&lt;home dir&gt;
+                        --shell=&lt;path to shell exe&gt;
+            </computeroutput>
+        </literallayout>
+     </para>        
   </refsect1>
+  
   <refsect1>
-    <title>Identity management</title>
+    <title>Delete User</title>
     <para>
-        The list of stored identities that the gsso-example application is allowed
-        to use can be obtained with <userinput>gsso-example --query-identities</userinput>:
-        <literallayout><computeroutput>
-<userinput>> gsso-example --query-identities</userinput>
-Available identities:
-        id=27 caption='My test identity'
-        id=28 caption='Another test identity'
-        </computeroutput></literallayout>
-    </para>
+        User can be deleted with flag <userinput>--delete-user</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --delete-user &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --uid=&lt;uid&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+    
+  <refsect1>
+    <title>Update User</title>
     <para>
-        To create an identity, use <userinput>--create-identity</userinput> option
-        with identity caption (user-readable name) and <userinput>--identity-method</userinput>
-        with the authentication method that the identity will be using.
-        <literallayout><computeroutput>
-<userinput>> gsso-example --create-identity="My test identity" --identity-method=password</userinput>
-Identity stored with id 28            
-        </computeroutput></literallayout>
-    </para>
+        User can be update with flag <userinput>--update-user</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --update-user &lt;mandatory-args&gt; &lt;update-args&gt;</userinput>:
+                    mandatory-args are:
+                        --uid=&lt;uid&gt; 
+                    possible update-args are:    
+                        --usecret=&lt;secret&gt;
+                        --realname=&lt;realname&gt;
+                        --office=&lt;office location&gt;
+                        --officephone=&lt;office phone&gt;
+                        --homephone=&lt;home phone&gt;
+                        --shell=&lt;path to shell exe&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+
+  <refsect1>
+    <title>Get User</title>
     <para>
-        To remove an identity, use <userinput>--remove-identity</userinput> option
-        with identity id:
-        <literallayout><computeroutput>
-<userinput>> gsso-example --remove-identity=28</userinput>
-Identity removed
-        </computeroutput></literallayout>
-    </para>
+        User data can be retrieved with flag <userinput>--get-user</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --get-user &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --uid=&lt;uid&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
   </refsect1>
+  
   <refsect1>
-    <title>Using 'password' authentication method</title>
+    <title>Get User By Name</title>
     <para>
-        'password' authentication simply returns to the application the username
-        and the password associated with an identity. If they haven't been stored
-        in gSSO secret database, they're asked from the user through gSSO UI.
-    </para>
+        User data can be retrieved with flag <userinput>--get-user-by-name</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --get-user-by-name &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --username=&lt;username&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+  
+  <refsect1>
+    <title>Add Group</title>
     <para>
-        To use the method, first create an identity with authentication method
-        set to 'password' (as shown above), note its identitiy id and then run:
-        <literallayout><computeroutput>
-<userinput>> gsso-example --get-password=27</userinput>
-Geting password
-Got response: {'UserName': &lt;'megauser'>, 'Secret': &lt;'megapassword'>}
-        </computeroutput></literallayout>
-    </para>   
+        Group can be added with flag <userinput>--add-group</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --add-group &lt;mandatory-args&gt; &lt;optional-args&gt;</userinput>:
+                    mandatory-args are:
+                        --groupname=&lt;groupname&gt;
+                        --grouptype=&lt;grouptype&gt;
+                        possible grouptypes are: system(1), user(2).
+                    optional-args are:
+                        --gsecret=&lt;secret&gt;
+            </computeroutput>
+        </literallayout>
+     </para>        
   </refsect1>
+      
   <refsect1>
-    <title>Using 'oauth' authentication method</title>
+    <title>Delete Group</title>
     <para>
-        'oauth' authentication method is used to obtain an OAuth1 or OAuth2 
-        authentication token from a remote service over HTTP. An application
-        needs to supply a few service-specific parameters when initiating the
-        authentication. gSSO example application supports obtaining an oauth
-        token from Google service (google-specific parameters are hardcoded
-        into the app source code).
-    </para>
+        Group can be deleted with flag <userinput>--delete-group</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --delete-group &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --gid=&lt;gid&gt;
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+  
+  <refsect1>
+    <title>Update Group</title>
     <para>
-        Obtaining an OAuth token may also include authorization of the application
-        by the user, which is done through user interaction with the service webpages
-        that are shown by gSSO UI. From the application point of view this authorization
-        happens completely transparently behind the scenes.
-    </para>
+        Group can be updated with flag <userinput>--udpate-group</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --update-group &lt;mandatory-args&gt; &lt;update-args&gt;</userinput>:
+                    mandatory-args are:
+                        --gid=&lt;gid&gt;
+                    possible update-args are:    
+                        --gsecret=&lt;secret&gt;
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+  
+  <refsect1>
+    <title>Get Group</title>
     <para>
-        Before trying the example, if you're behind a proxy, and are using 
-        the Gtk-based gSSO UI, make sure that your GNOME proxy settings are
-        correctly configured, either via GNOME UI, or via command line:
-        <literallayout><computeroutput>
-<userinput>> gsettings list-recursively org.gnome.system.proxy</userinput>
-        </computeroutput></literallayout>
-        To set the proxy, use:
-        <literallayout><computeroutput>
-<userinput>> gsettings set org.gnome.system.proxy mode 'manual'
-> gsettings set org.gnome.system.proxy.http port 8080
-> gsettings set org.gnome.system.proxy.http host 'myproxy.domain.lan'</userinput>
-        </computeroutput></literallayout>
-        To disable the proxy, use
-        <literallayout><computeroutput>
-<userinput>> gsettings set org.gnome.system.proxy mode 'none'</userinput>
-        </computeroutput></literallayout>
-        See all available configurations keys here:
-        <ulink url="http://developer.gnome.org/ProxyConfiguration/">
-        http://developer.gnome.org/ProxyConfiguration/</ulink>
-    </para>
+        Group data can be retrieved with flag <userinput>--get-group</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --get-group &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --gid=&lt;gid&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+
+  <refsect1>
+    <title>Get Group By Name</title>
     <para>
-        You would also need a client identifier and key from Google. Instructions
-        about how to get them are available at 
-        <ulink url="https://developers.google.com/console/help/#generatingoauth2">https://developers.google.com/console/help/#generatingoauth2</ulink>
-    </para>
+        Group data can be retrieved with flag <userinput>--get-group-by-name</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --get-group-by-name &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --groupname=&lt;groupname&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+      
+  <refsect1>
+    <title>Add member To Group</title>
     <para>
-        Once the above are settled, create an identity with 'oauth' method
-        (as shown above) and issue:
-        <literallayout><computeroutput>
-<userinput>> gsso-example --get-google-token=12 --client-id=xxxxxxx.apps.googleusercontent.com --client-secret=yyyyyyyyyyyyy</userinput>
-Geting token
-Got response: {'Scope': &lt;'email'>, 'AccessToken': &lt;'tokenvalue'>, 
-               'TokenParameters': &lt;@a{sv} {}>, 'TokenType': &lt;'Bearer'>, 
-               'RefreshToken': &lt;'refreshtokenvalue'>, 'Duration': &lt;int64 3600>, 
-               'Timestamp': &lt;int64 1377707888>}                
-        </computeroutput></literallayout>
-    </para>
+        New member can be added to a group with flag <userinput>--add-member</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --add-member &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --gid=&lt;gid&gt; 
+                        --mem_uid=&lt;mem_uid&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
   </refsect1>
+  
+  <refsect1>
+    <title>Delete member From Group</title>
+    <para>
+        A member can be removed from the group with flag <userinput>--delete-member</userinput>:
+        <literallayout>
+            <computeroutput>
+                <userinput>gum-example --delete-member &lt;mandatory-args&gt;</userinput>:
+                    mandatory-args are:
+                        --gid=&lt;gid&gt; 
+                        --mem_uid=&lt;mem_uid&gt; 
+            </computeroutput>
+        </literallayout>
+     </para>        
+  </refsect1>
+
 </refentry> 
\ No newline at end of file

diff --git a/docs/gumd-docs.sgml b/docs/gumd-docs.sgml
index dae4bfa..b97ed1b 100644 (file)
--- a/docs/gumd-docs.sgml
+++ b/docs/gumd-docs.sgml
@@ -7,69 +7,57 @@
 <book id="index">
     <bookinfo>
         <title>gumd and libgum API Reference Manual</title>
-        <releaseinfo> This document is for gumd and libgum, version &version;.
+        <releaseinfo>This document discusses the details of user management 
+        daemon (gumd) and client library (libgum) with version &version;.
         </releaseinfo>
     </bookinfo>
 
-    <part id="um-overview">
-        <title>User management Overview</title>
-        
-        <xi:include href="introduction.xml"/>
-        <xi:include href="examples.xml"/>
-    </part>
+    <xi:include href="introduction.xml"/>
   
-    <part id="um-common">
-        <title>Common</title>
-        <chapter>
-            <xi:include href="building.xml"/>
-        </chapter>
+    <xi:include href="building.xml"/>
+        
+    <chapter>
+        <title>Daemon(gumd) configuration</title>
+        <xi:include href="xml/gum-config.xml"/>
+        <xi:include href="xml/gum-config-general.xml"/>
+        <xi:include href="xml/gum-config-dbus.xml"/>
+    </chapter>
+    
+    <xi:include href="examples.xml"/>
 
-        <chapter>
-            <title>Miscellaneous</title>
-            <xi:include href="xml/gum-error.xml"/>
-            <xi:include href="xml/gum-log.xml"/>
-            <xi:include href="xml/gum-utils.xml"/>
-        </chapter>
-    </part>
+    <chapter>
+        <title>Miscellaneous</title>
+        <xi:include href="xml/gum-error.xml"/>
+        <xi:include href="xml/gum-log.xml"/>
+        <xi:include href="xml/gum-utils.xml"/>
+    </chapter>
 
-    <part id="um-gumd">
-        <title>gumd</title>
-           
-        <chapter>
-            <title>gumd configuration</title>
-            <xi:include href="xml/gum-config.xml"/>
-            <xi:include href="xml/gum-config-general.xml"/>
-            <xi:include href="xml/gum-config-dbus.xml"/>
-        </chapter>
-    </part>
-    
-    <part id="um-objects">
+    <chapter>
         <title>gumd and libgum Objects</title>
         <chapter id="object-tree">
             <title>Object Hierarchy</title>
             <xi:include href="xml/tree_index.sgml"/>
         </chapter>
-    </part>
+    </chapter>
   
-    <part id="appendices">
+    <chapter>
         <title>Appendices</title>
-        <index id="api-index-full">
-            <title>API Index</title>
-            <xi:include href="xml/api-index-full.xml">
-                <xi:fallback />
-            </xi:include>
-        </index>
-      
-        <index id="deprecated-api-index" role="deprecated">
-            <title>Index of deprecated API</title>
-            <xi:include href="xml/api-index-deprecated.xml">
-                <xi:fallback />
-            </xi:include>
-        </index>
+        <xi:include href="xml/api-index-full.xml">
+            <xi:fallback />
+        </xi:include>
+    </chapter>  
+    
+    <chapter>        
+        <title>Deprecated APIs</title>
+        <xi:include href="xml/api-index-deprecated.xml">
+            <xi:fallback />
+        </xi:include>
+    </chapter>
     
+    <chapter>    
         <xi:include href="xml/annotation-glossary.xml">
             <xi:fallback />
         </xi:include>
-    </part>
+    </chapter>
   
 </book>

diff --git a/docs/introduction.xml b/docs/introduction.xml
index b5f5b8d..0751a26 100644 (file)
--- a/docs/introduction.xml
+++ b/docs/introduction.xml
@@ -4,90 +4,27 @@
 ]>
 <refentry id="um-intro">
   <refmeta>
-    <refentrytitle>gumd introduction</refentrytitle>
+    <refentrytitle>Introduction</refentrytitle>
   </refmeta>
 
   <refsect1>
-    <title>What is gumd?</title>
+    <title>What is gumd/libgum?</title>
     <para>
-        gumd is a framework for centrally storing authentication credentials
-        and handling authentication on behalf of applications as requested by
-        them. It consists of a gumd daemon that implements secure storage of 
-        login credentials (for example usernames and passwords), plugins for 
-        different authentication systems and a client library (libgsignond-glib) 
-        for applications to communicate with this system.        
+        gumd and libgum together provides a framework for creating, deleting
+        and modifying user and groups in the system. gumd is a daemon that
+        implements the functionality that provides access to user/group
+        database and libgum is a client library for applications to communicate
+        with this system.        
     </para>
     <para>
-        By using this client library, an application can authenticate to a
-        (usually remote) service using an existing set of credentials, and manage
-        the credentials database as well (subject to access restrictions).
+        By using libgum client library, an application can query/create/delete/modify
+        users' and groups' database.
     </para>
     <para>
-        Some authentication methods require interaction with the user, for example
-        to request a username and password, or to show a webpage with which the
-        user is expected to interact. This functionality is provided by gumd UI
-        component, and it's completely invisible from the applications' point
-        of view.
-    </para>
-    <para>
-        The client library (libgsignond-glib) interacts with gumd daemon through
-        D-Bus. These D-Bus APIs should not be used directly as they are not documented, subject
-        to change and don't come with backwards compatibility guarantees.
-    </para>
-  </refsect1>
-  <refsect1>
-    <title>Terminology</title>
-    <para>
-        gumd is built around a few key concepts which are explained below:
-        <itemizedlist>
-            <listitem>
-                <para>
-                    <systemitem>Authentication service</systemitem>: the top level
-                    object representing the gumd service. It can be used to query
-                    existing identities, available
-                    authentication menthods and their mechanisms. Authentication
-                    service is represented in the client library by
-                    <link linkend="SignonAuthService">SignonAuthService objects</link>.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    <systemitem>Identity</systemitem>: This is a local object representing a record in the
-                    credentials DB. It contains information about the username and password (the
-                    latter is write-only), plus some metadata such as a descriptive caption, access
-                    control list, reference count, and other metadata. Identities are identified by
-                    numeric identity IDs and represented in the client library by <link linkend="SignonIdentity">
-                    SignonIdentity</link> objects.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    <systemitem>Security context</systemitem>: The information that is used by gumd daemon
-                    to make access control decisions when applications try to access identities
-                    for reading, writing, or starting authentication sessions. Security contexts
-                    consist of two strings: the system context which identifies the application process,
-                    and application context which identifies what the application process is doing. Security
-                    contexts are represented in the client library by <link linkend="SignonSecurityContext">
-                    SignonSecurityContext</link> objects.        
-                </para>
-            </listitem>            
-            <listitem>
-                <para>
-                    <systemitem>Authentication method</systemitem>: the SSO daemon supports different
-                    authentication methods, each implemented by a plugin. Well known examples of
-                    authentication methods include <ulink url="http://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer">SASL</ulink>,
-                    or <ulink url="http://en.wikipedia.org/wiki/Oauth">OAuth</ulink>. Authentication methods
-                    might support different authentication mechanisms, which are method-specific variants of authentication process.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    <systemitem>Authentication session</systemitem>: the process of performing the authentication.
-                    It is represented in the client library by <link linkend="SignonAuthSession">SignonAuthSession objects</link>.
-                    Authentication sessions are started from existing identites.
-                </para>
-            </listitem>
-        </itemizedlist>        
+        The client library, libgum, interacts with gumd daemon through
+        D-Bus. These D-Bus APIs should not be used directly as they are not
+        documented, subject to change and don't come with backwards
+        compatibility guarantees.
     </para>
   </refsect1>
 </refentry>
\ No newline at end of file