Updated/added.

diff --git a/doc/draft-riikonen-silc-commands-06.nroff b/doc/draft-riikonen-silc-commands-06.nroff
index dc37da7be81103c8f39d77618108ab4a6c2faf77..50d151fdbf8a06263c7f5fa5ecd4bc44e4b16ce5 100644 (file)
--- a/doc/draft-riikonen-silc-commands-06.nroff
+++ b/doc/draft-riikonen-silc-commands-06.nroff
@@ -213,7 +213,10 @@ ID, length of the ID and the actual ID data.  This way variable length
 ID's can be sent as arguments.
 
 All passphrases that may be sent in commands as arguments MUST be
-UTF-8 [RFC2279] encoded.
+UTF-8 [RFC2279] encoded.  All strings, with exeption of nicknames and
+channel names [SILC1], are UTF-8 encoded.  This includes strings like
+algorithm names, quit, kick and kill messages, service identifiers and
+others.
 
 All public keys and certificates that are sent as arguments are actually
 Public Key Payloads [SILC2].  This way it is possible to send different
@@ -1995,7 +1998,7 @@ List of all defined commands in SILC follows.
         remote service.  The authentication to a service may be based
         on previous agreement with the requester and the service
         provider.  The command MAY also take additional service
-        specific arguments.
+        specific arguments.  The <service name> is UTF-8 string.
 
         This document does not specify any services.  How the services
         are configured and put available in a server is also out of
@@ -2383,7 +2386,8 @@ List of all defined status types:
    46   SILC_STATUS_ERR_UNKOWN_ALGORITHM
 
         "The algorithm was not supported."  The server does not support the
-        requested algorithm.
+        requested algorithm.  The next argument MUST be the algorithm name
+        string.
 
    47   SILC_STATUS_ERR_NO_SUCH_SERVER_ID
 
@@ -2399,7 +2403,7 @@ List of all defined status types:
    49   SILC_STATUS_ERR_NO_SUCH_SERVICE
 
         "Service does not exist".  Requested service identifier is
-        unknown.
+        unknown.  The next argument MUST be the service identifier.
 
    50   SILC_STATUS_ERR_NOT_AUTHENTICATED
 

diff --git a/lib/doc/command_reply_args.html b/lib/doc/command_reply_args.html
index bec1383e4adb16135da2c0d456024dd32a19612b..fa9019b08ed3c8be09d54d3c956d99d70ef239cc 100644 (file)
--- a/lib/doc/command_reply_args.html
+++ b/lib/doc/command_reply_args.html
@@ -11,6 +11,15 @@ specific arguments to the application.  This document describes these
 arguments for all command replies to help SILC client software developers
 to process them.
 
+<br />&nbsp;<br />
+<b>NOTE: </b>The following list of command reply arguments are sent when
+the command was executed successfully.  If an error occurred, the
+`command_reply' client operation's 'success' argument is FALSE, and the
+'status' argument includes the error status.  In this case the arguments
+returned are dependent of the 'status' argument.  See all
+<a href="silcstatus_args.html">SilcStatus error arguments</a> for these
+arguments.
+
 <br />&nbsp;<br />&nbsp;<br />
 <b>command_reply Client Library operation</b>
 
@@ -34,7 +43,8 @@ is the raw SilcCommandPayload and application usually ignores it, the
 'success' boolean value indicates whether the earlier command was a success
 or not, the 'command' is the command reply enumeration, and the 'status'
 indicates the status of the command reply.  If 'success' is FALSE then
-'status' includes error status.
+'status' includes error status (see <a href="silcstatus_args.html">SilcStatus
+error arguments</a>).
 
 <br />&nbsp;<br />
 Rest of the arguments are 'command' specific and implementation should
@@ -68,8 +78,11 @@ library sends in the 'command_reply' client operation to the application.
 By default all arguments that the library sends to application are valid
 pointers.  However, it is possible that some pointers may be NULL.  If
 this is the case it is separately mentioned that the argument may be NULL.
-In this case application must ignore that argument.  The 'command_reply'
-arguments per SilcCommand is as follows:
+In this case application must ignore that argument.
+
+<br />&nbsp;<br />
+The 'command_reply' arguments for successful SilcCommand replies are as
+follows:
 
 <br />&nbsp;<br />
 <table border="1" width="100%" cellpadding="3" cellspacing="0">

diff --git a/lib/doc/silcstatus_args.html b/lib/doc/silcstatus_args.html
new file mode 100644 (file)
index 0000000..da54fb1
--- /dev/null
+++ b/lib/doc/silcstatus_args.html
@@ -0,0 +1,491 @@
+<big><b>SilcStatus Arguments</b></big>
+
+<br />&nbsp;<br />
+The <a href="silccore-SilcStatus.html">SilcStatus</a> is used to indicate
+a status (usually error status) of command execution and command reply
+status.  It is also used to deliver disconnection status when server
+disconnects client from the server.  For application it is mainly important
+in case of `command_reply' client operation, where the SilcStatus indicates
+the error status of the command that was executed.  If error occurred the
+arguments returned by the `command_reply' are then dependent of the SilcStatus
+type instead of the <a href="command_reply_args.html">SilcCommand
+arguments</a>.
+
+<br />&nbsp;<br />
+This documents describes how the application should interpret the SilcStatus
+type in the `command_reply' client operation to be able to handle all
+error conditions properly.  Any status type can be returned for any
+SilcCommand.  For this reason application should be able to handle any
+error with any command.
+
+
+<br />&nbsp;<br />&nbsp;<br />
+<b>Error Status In command_reply Client Operation</b>
+
+<br />&nbsp;<br />
+When error occurs in execution of a command the `command_reply' client
+operation is called with error status.  In this case the 'success'
+argument of the client operation is set to FALSE, to indicate that command
+execution failed, and the 'status' argument indicates the error.
+If the 'status' argument is SILC_STATUS_OK then error did not occur and the
+arguments are as described in <a href="command_reply_args.html">SilcCommand
+arguments</a>.
+
+<br />&nbsp;<br />
+Application should handle the error status arguments by the SilcStatus
+type for example in a <tt>switch</tt> statement.  The SilcStatus values
+are defined in lib/silccore/silcstatus.h header file.  A short example.
+
+<br />&nbsp;<br />
+<tt>
+&nbsp;&nbsp;switch(status)<br />
+&nbsp;&nbsp;&nbsp;&nbsp;{<br />
+&nbsp;&nbsp;&nbsp;&nbsp;case SILC_STATUS_ERR_NO_SUCH_NICK:<br />
+&nbsp;&nbsp;&nbsp;&nbsp;...<br />
+&nbsp;&nbsp;&nbsp;&nbsp;nick = va_arg(va, char *);<br />
+&nbsp;&nbsp;&nbsp;&nbsp;...<br />
+&nbsp;&nbsp;&nbsp;&nbsp;break;<br />
+&nbsp;&nbsp;&nbsp;&nbsp;case SILC_STATUS_ERR_NO_SUCH_CHANNEL:<br />
+&nbsp;&nbsp;&nbsp;&nbsp;...<br />
+&nbsp;&nbsp;&nbsp;&nbsp;break;<br />
+&nbsp;&nbsp;&nbsp;&nbsp;case SILC_STATUS_ERR_NO_SUCH_SERVER:<br />
+&nbsp;&nbsp;&nbsp;&nbsp;...<br />
+&nbsp;&nbsp;&nbsp;&nbsp;break;<br />
+&nbsp;&nbsp;&nbsp;&nbsp;...<br />
+&nbsp;&nbsp;&nbsp;&nbsp;default:<br />
+&nbsp;&nbsp;&nbsp;&nbsp;break;<br />
+&nbsp;&nbsp;&nbsp;&nbsp;}
+</tt>
+
+
+<br />&nbsp;<br />&nbsp;<br />
+<b>Arguments</b>
+
+<br />&nbsp;<br />
+The following table describes all status values and arguments that the client
+library sends in the 'command_reply' client operation to the application
+in case of error.  By default all arguments that the library sends to
+application are valid pointers.  However, it is possible that some pointers
+may be NULL.  If this is the case it is separately mentioned that the
+argument may be NULL.  In this case application must ignore that argument.
+
+<br />&nbsp;<br />
+The 'command_reply' arguments in case of error are as follows:
+
+<br />&nbsp;<br />
+<table border="1" width="100%" cellpadding="3" cellspacing="0">
+
+<tr>
+<td><small>Name</td>
+<td><small>Description</td>
+<td width="50%"><small>Error Arguments</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_OK</td>
+<td><small>
+No error.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SUCH_NICK</td>
+<td><small>
+Requested nickname does not exist.  Argument is the unknown name.
+</td>
+<td width="50%"><small>const char *nickname
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SUCH_CHANNEL</td>
+<td><small>
+The requested channel does not exist.  Argument is the unknown name.
+</td>
+<td width="50%"><small>const char *channel_name
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SUCH_SERVER</td>
+<td><small>
+The requested server does not exist.  Argument is the unknown name.
+</td>
+<td width="50%"><small>const char *server_name
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_RECIPIENT</td>
+<td><small>
+Command required recipient but none was provided.  No arguments returned.
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_UNKNOWN_COMMAND</td>
+<td><small>
+Command sent to server is unknown or unsupported by the server.  No
+arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_WILDCARDS</td>
+<td><small>
+Wildcards were provided by they were not permitted.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_CLIENT_ID</td>
+<td><small>
+Client ID was expected as command parameter but was not found.  No
+arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_CHANNEL_ID</td>
+<td><small>
+Channel ID was expected as command parameter but was not found.  No
+arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SERVER_ID</td>
+<td><small>
+Server ID was expected as command parameter but was not found.  No
+arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_BAD_CLIENT_ID</td>
+<td><small>
+Client ID provided was malformed.  Returns the malformed ID.
+</td>
+<td width="50%"><small>const SilcClientID *client_id
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_BAD_CHANNEL_ID</td>
+<td><small>
+Channel ID provided was malformed.  Returns the malformed ID.
+</td>
+<td width="50%"><small>const SilcChannelID *channel_id
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_BAD_SERVER_ID</td>
+<td><small>
+Server ID provided was malformed.  Returns the malformed ID.
+</td>
+<td width="50%"><small>const SilcServerID *server_id
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SUCH_CLIENT_ID</td>
+<td><small>
+Client ID provided does not exist.  The unknown ID is returned.
+</td>
+<td width="50%"><small>const SilcClientID *client_id
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID</td>
+<td><small>
+Channel ID provided does not exist.  The unknown ID is returned.
+</td>
+<td width="50%"><small>const SilcChannelID *channel_id
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SUCH_SERVER_ID</td>
+<td><small>
+Server ID provided does not exist.  The unknown ID is returned.
+</td>
+<td width="50%"><small>const SilcServerID *server_id
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NOT_ON_CHANNEL</td>
+<td><small>
+The command required for you to be on channel but you were not.
+The channel is returned.  The 'channel' may be NULL.
+</td>
+<td width="50%"><small>SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_USER_NOT_ON_CHANNEL</td>
+<td><small>
+The requested target client is not on requested channel.  Returns the
+target client and channel.  The 'target_client' and 'channel' may be NULL.
+</td>
+<td width="50%"><small>SilcClientEntry target_client, SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_USER_ON_CHANNEL</td>
+<td><small>
+User were invited on channel they already are on.  Returns the
+target client and channel.  The 'target_client' and 'channel' may be NULL.
+</td>
+<td width="50%"><small>SilcClientEntry target_client, SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NOT_REGISTERED</td>
+<td><small>
+User executed command that requires the client to be registered on the
+server before it may be executed.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NOT_ENOUGH_PARAMS</td>
+<td><small>
+Command required more parameters than provided.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_TOO_MANY_PARAMS</td>
+<td><small>
+Too many parameters provided for the command.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_PERM_DENIED</td>
+<td><small>
+Generic permission denied error status, to indicat disallowed access.
+No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_BAD_PASSWORD</td>
+<td><small>
+Password provided for channel were not accepted.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_CHANNEL_IS_FULL</td>
+<td><small>
+The channel is full and client cannot join the channel.  Returns the
+channel, which may be NULL.
+</td>
+<td width="50%"><small>SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NOT_INVITED</td>
+<td><small>
+The channel is invite only channel and client has not been invited.
+Returns the channel, which may be NULL.
+</td>
+<td width="50%"><small>SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_BANNED_FROM_CHANNEL</td>
+<td><small>
+The client has been banned from the channel.  Returns the channel, which
+may be NULL.
+</td>
+<td width="50%"><small>SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_UNKNOWN_MODE</td>
+<td><small>
+Mode provided by the client was unknown to or unsupported by the server.
+No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NOT_YOU</td>
+<td><small>
+User tried to change someone else's mode which is not allowed.
+No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_CHANNEL_PRIV</td>
+<td><small>
+Command may be executed only by channel operator.  The next argument is
+the channel, which may be NULL.
+</td>
+<td width="50%"><small>SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_CHANNEL_FOPRIV</td>
+<td><small>
+Command may be executed only by channel founder.  The next argument is
+the channel, which may be NULL.
+</td>
+<td width="50%"><small>SilcChannelEntry channel
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SERVER_PRIV</td>
+<td><small>
+Command may be executed only by server operator.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_ROUTER_PRIV</td>
+<td><small>
+Command may be executed only by router (SILC) operator.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_BAD_NICKNAME</td>
+<td><small>
+Nickname requested contained illegal characters or was malformed.  No
+arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_BAD_CHANNEL</td>
+<td><small>
+Channel name requested contained illegal characters or was malformed.  No
+arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_AUTH_FAILED</td>
+<td><small>
+The authentication data (passphrase or digital signature) sent as argument
+was wrong and thus authentication failed.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_UNKNOWN_ALGORITHM</td>
+<td><small>
+The server does not support requested algorithm.  Returns the unknown
+algorithm.
+</td>
+<td width="50%"><small>const char *alg_name
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_RESOURCE_LIMIT</td>
+<td><small>
+Server cannot or will not accept the action due to resource limitations.
+No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_NO_SUCH_SERVICE</td>
+<td><small>
+Requestes service identifier is unknown.  Returns the unknown service
+identifier.
+</td>
+<td width="50%"><small>const char *service_identifier
+</td>
+</tr>
+
+<tr>
+<td><small>SILC_STATUS_ERR_TIMEDOUT</td>
+<td><small>
+Operation (command execution) or service request timed out, and thus was
+not processed.  This usually happens due to network failure between servers
+and routers in the network.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+<tr>
+
+<td><small>SILC_STATUS_ERR_UNSUPPORTED_PUBLIC_KEY</td>
+<td><small>
+The public key or certificate type is not supported in ths implementation.
+No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+<td><small>SILC_STATUS_ERR_OPERATION_ALLOWED</td>
+<td><small>
+A operation, for example a command, is not allowed or it's execution is
+not allowed.  No arguments returned.
+</td>
+<td width="50%"><small>N/A
+</td>
+</tr>
+
+</table>
+
+<br />&nbsp;<br />
+SILC protocol defines some additional status types but those status
+types are not returned in `command_reply' client operation.  Only
+the status types listed above are delivered to application.