From a37836766cadbd4ad8e0cb575c2f48689f89993d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=A4ckerlin?= Date: Mon, 9 Nov 2015 22:13:32 +0000 Subject: [PATCH] improved documentation, better api documentation --- doc/doxyfile.in | 6 ++--- html/checknewuser.php | 44 ++++++++++++++---------------- html/get.php | 38 +++++++++++++------------- html/login.php | 62 +++++++++++++++++++++---------------------- html/pubkey.php | 51 +++++++++++++++++------------------ html/send.php | 60 ++++++++++++++++++++--------------------- 6 files changed, 127 insertions(+), 134 deletions(-) diff --git a/doc/doxyfile.in b/doc/doxyfile.in index 7424e78..e2a2e88 100644 --- a/doc/doxyfile.in +++ b/doc/doxyfile.in @@ -226,7 +226,7 @@ ALIASES += "instancemutex=\par Reentrant:\nAccess is locked with per instance mu ALIASES += "classmutex=\par Reentrant:\nAccess is locked with class static mutex @c " ALIASES += "license=\par License\n" ALIASES += "copy=\par Copyright\n" - +ALIASES += "api=\xrefitem api \"API Call\" \"\"" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" # will allow you to use the command class in the itcl::class meaning. @@ -785,7 +785,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = @top_srcdir@/openpgp.js +EXCLUDE = @top_srcdir@/html/openpgp.js # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -2223,7 +2223,7 @@ DOT_IMAGE_FORMAT = svg # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -INTERACTIVE_SVG = YES +INTERACTIVE_SVG = NO # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. diff --git a/html/checknewuser.php b/html/checknewuser.php index c170db2..89b0d89 100644 --- a/html/checknewuser.php +++ b/html/checknewuser.php @@ -2,37 +2,33 @@ /*! @file @id $Id$ +*/ +// 1 2 3 4 5 6 7 8 +// 45678901234567890123456789012345678901234567890123456789012345678901234567890 - @see @ref apichecknewuser - - @page api Server API - - @tableofcontents - - @section apichecknewuser Check If User Exists - - API-call checknewuser.php - - Check if a user exists in the server's user table. +/// Check if a user exists +/** Check if a user exists in the server's user table. - @param user user name to check + @param $user user name to check @return json encoded value: - 'user name as string', if user does exist - null, if user does not exist or in case of error -*/ -// 1 2 3 4 5 6 7 8 -// 45678901234567890123456789012345678901234567890123456789012345678901234567890 -try { - require_once("opendb.php"); - $user = $db->real_escape_string($_REQUEST['user']); - $q = $db->query("select * from user where name='$user';"); - if ($q->num_rows==0) { - echo json_encode($_REQUEST['user']); - } else { + @api Check If User Exists +*/ +function checknewuser($user) { + try { + require_once("opendb.php"); + $dbuser = $db->real_escape_string($user); + $q = $db->query("select * from user where name='$dbuser';"); + if ($q->num_rows==0) { + echo json_encode($user); + } else { + echo json_encode(null); + } + } catch (Exception $e) { echo json_encode(null); } -} catch (Exception $e) { - echo json_encode(null); } +checknewuser($_REQUEST['user']); ?> \ No newline at end of file diff --git a/html/get.php b/html/get.php index d09918c..6a9c584 100644 --- a/html/get.php +++ b/html/get.php @@ -2,18 +2,15 @@ /*! @file @id $Id$ +*/ +// 1 2 3 4 5 6 7 8 +// 45678901234567890123456789012345678901234567890123456789012345678901234567890 - @see @ref apiget - - @page api - - @section apiget Get Messages - - API-call get.php - Get all messages that are newer than start. +/// Get new messages +/** Get all messages that are newer than @c $start. - @param start Number of message to start with. + @param $start Number of message to start with. @return json encoded array of messages: @code [ @@ -25,16 +22,19 @@ }, ... ] @endcode + + @api Get New Messages */ -// 1 2 3 4 5 6 7 8 -// 45678901234567890123456789012345678901234567890123456789012345678901234567890 -try { - require_once("opendb.php"); - $start = $db->real_escape_string($_REQUEST['start']); - $q = $db->query("select id, UNIX_TIMESTAMP(time) as time, user, msg from message where id>$start;"); - if ($q) echo json_encode($q->fetch_all(MYSQLI_ASSOC)); - else echo json_encode(null); -} catch (Exception $e) { - echo json_encode(null); +function get($start) { + try { + require_once("opendb.php"); + $start = $db->real_escape_string($start); + $q = $db->query("select id, UNIX_TIMESTAMP(time) as time, user, msg from message where id>$start;"); + if ($q) echo json_encode($q->fetch_all(MYSQLI_ASSOC)); + else echo json_encode(null); + } catch (Exception $e) { + echo json_encode(null); + } } +get($_REQUEST['start']); ?> diff --git a/html/login.php b/html/login.php index 8a56d32..fa718f3 100644 --- a/html/login.php +++ b/html/login.php @@ -2,46 +2,46 @@ /*! @file @id $Id$ +*/ +// 1 2 3 4 5 6 7 8 +// 45678901234567890123456789012345678901234567890123456789012345678901234567890 - @see @ref apilogin - - @page api - - @section apilogin Login - - API-call login.php - Check if a user is consistent to the data in the server's database - or create a user, if he does not yet exist in the @ref usertable +/// Verify a user +/** Check if a user is consistent to the data in the server's database + or create a user, if he does not yet exist in the usertable (and the user name is available). - @param user user's name - @param pubkey user's public key + @param $user user's name + @param $pubkey user's public key @return json encoded status with text: - success() in case of success (user exists or has been created) - error() in case of mismatch + + @api Verify a User */ -// 1 2 3 4 5 6 7 8 -// 45678901234567890123456789012345678901234567890123456789012345678901234567890 -try { - require_once("opendb.php"); - $user = $db->real_escape_string($_REQUEST['user']); - $pubkey = $db->real_escape_string($_REQUEST['pubkey']); - if ($user=="safechat") error("username safechat is reserved for server"); - $verify = gnupg_import($pgp, $_REQUEST['pubkey']); - if (!$verify) error("wrong identity"); - $q = $db->query("select * from user where name='$user' and pubkey='$pubkey';"); - if ($q->num_rows==1) { - success("user $user found on server"); - } elseif ($q->num_rows==0) { - $q = $db->query("insert into user (name, pubkey) values ('$user', '$pubkey');"); - if (!$q) error("creation of user failed"); - success("user $user created on server"); - } else { - error("server database defect"); +function login($user, $pubkey) { + try { + require_once("opendb.php"); + if ($user=="safechat") error("username safechat is reserved for server"); + $verify = gnupg_import($pgp, $pubkey); + if (!$verify) error("wrong identity"); + $user = $db->real_escape_string($user); + $pubkey = $db->real_escape_string($pubkey); + $q = $db->query("select * from user where name='$user' and pubkey='$pubkey';"); + if ($q->num_rows==1) { + success("user $user found on server"); + } elseif ($q->num_rows==0) { + $q = $db->query("insert into user (name, pubkey) values ('$user', '$pubkey');"); + if (!$q) error("creation of user failed"); + success("user $user created on server"); + } else { + error("server database defect"); + } + } catch (Exception $e) { + error("login failed"); } -} catch (Exception $e) { - error("login failed"); } +login($_REQUEST['user'], $_REQUEST['pubkey']); ?> diff --git a/html/pubkey.php b/html/pubkey.php index 047127c..f1a2b77 100644 --- a/html/pubkey.php +++ b/html/pubkey.php @@ -2,18 +2,14 @@ /*! @file @id $Id$ +*/ +// 1 2 3 4 5 6 7 8 +// 45678901234567890123456789012345678901234567890123456789012345678901234567890 - @see @ref apipubkey - - @page api - - @section apipubkey Get Public Key - - API-call pubkey.php - - Get the public key of a user. +/// Get a user's public key +/** Get the public key of a user. - @param user Name of the user to ge public key from. + @param $user Name of the user to ge public key from. @return json encoded value: - @c null in case of error (user does not exist) @@ -22,24 +18,27 @@ pubkey: 'armored public key string' } @endcode + + @api Get A User's Public Key */ -// 1 2 3 4 5 6 7 8 -// 45678901234567890123456789012345678901234567890123456789012345678901234567890 -try { - require_once("usertable.php"); - $user = $db->real_escape_string($_REQUEST['user']); - $q = $db->query("select pubkey from user where name='$user';"); - /* if ($q->num_rows!=1 && $user=="safechat") { */ - /* require_once("optionstable.php"); */ - /* createSafechatUser(); */ - /* $q = $db->query("select pubkey from user where name='$user';"); */ - /* } */ - if ($q->num_rows==1) { - echo json_encode($q->fetch_row()[0]); - } else { +function pubkey($user) { + try { + require_once("opendb.php"); + $user = $db->real_escape_string($user); + $q = $db->query("select pubkey from user where name='$user';"); + /* if ($q->num_rows!=1 && $user=="safechat") { */ + /* require_once("optionstable.php"); */ + /* createSafechatUser(); */ + /* $q = $db->query("select pubkey from user where name='$user';"); */ + /* } */ + if ($q->num_rows==1) { + echo json_encode($q->fetch_row()[0]); + } else { + echo json_encode(null); + } + } catch (Exception $e) { echo json_encode(null); } -} catch (Exception $e) { - echo json_encode(null); } +pubkey($_REQUEST['user']); ?> diff --git a/html/send.php b/html/send.php index 1cc7e7c..485bafd 100644 --- a/html/send.php +++ b/html/send.php @@ -2,47 +2,45 @@ /*! @file @id $Id$ +*/ +// 1 2 3 4 5 6 7 8 +// 45678901234567890123456789012345678901234567890123456789012345678901234567890 - @see @ref apisend - - @page api - - @section apisend Send Message To Server - - API-call send.php - - Send a message to the server. Sever checks if user exists and has +/// Send a message to the server +/** Server checks if user exists and has a valid public key. More test could be added later. - @param user The name of the user that send the message. + @param $user The name of the user that send the message. - @param msg The armored signed and encrypted message. There is a - limit of 100000 bytes for the message. + @param $msg The armored signed and encrypted message. There is a + limit of 100000 bytes for the message. @return - success() if the message has been stored successfully - error() in case of any error + + @api Send Message to Server */ -// 1 2 3 4 5 6 7 8 -// 45678901234567890123456789012345678901234567890123456789012345678901234567890 -try { - require_once("opendb.php"); - $user = $db->real_escape_string($_REQUEST['user']); - $msg = $db->real_escape_string($_REQUEST['msg']); - if (strlen($_REQUEST['msg'])>100000) error("message is too long"); - $q = $db->query("select pubkey from user where name='$user';"); - if (!$q || $q->num_rows!=1) error("user not found on server"); - $pubkey = gnupg_import($pgp, $q->fetch_row()[0]); - if (!$pubkey) error("wrong identity"); - $q = $db->query("insert into message (user, msg) values ('$user', '$msg');"); - if (!$q) { - error_log("Error storing message: ".$db->error); +function send($user, $msg) { + try { + require_once("opendb.php"); + $user = $db->real_escape_string($user); + $msg = $db->real_escape_string($msg); + if (strlen($_REQUEST['msg'])>100000) error("message is too long"); + $q = $db->query("select pubkey from user where name='$user';"); + if (!$q || $q->num_rows!=1) error("user not found on server"); + $pubkey = gnupg_import($pgp, $q->fetch_row()[0]); + if (!$pubkey) error("wrong identity"); + $q = $db->query("insert into message (user, msg) values ('$user', '$msg');"); + if (!$q) { + error_log("Error storing message: ".$db->error); + error("storing message failed"); + } + success("message stored"); + } catch (Exception $e) { + error_log("Error storing message: ".$e->message); error("storing message failed"); } - success("message stored"); -} catch (Exception $e) { - error_log("Error storing message: ".$e->message); - error("storing message failed"); } - +send($_REQUEST['user'], $_REQUEST['msg']); ?> \ No newline at end of file