[sr-dev] git:master: doc: rpc api documentation updated: the '.' modifier
Andrei Pelinescu-Onciul
andrei at iptel.org
Thu Jul 16 10:47:03 CEST 2009
Module: sip-router
Branch: master
Commit: 46fb4917c2163fd5c8bd01fdd866813211cd6ec7
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=46fb4917c2163fd5c8bd01fdd866813211cd6ec7
Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
Date: Thu Jul 16 09:36:22 2009 +0200
doc: rpc api documentation updated: the '.' modifier
---
doc/rpc/ser_rpc.txt | 59 ++++++++++++++++++++++++++++++++++++++------------
doc/rpc/ser_rpc.xml | 60 +++++++++++++++++++++++++++++++++++++++++++++------
2 files changed, 98 insertions(+), 21 deletions(-)
diff --git a/doc/rpc/ser_rpc.txt b/doc/rpc/ser_rpc.txt
index 778c03f..b2c5337 100644
--- a/doc/rpc/ser_rpc.txt
+++ b/doc/rpc/ser_rpc.txt
@@ -249,12 +249,13 @@ add("sd", string_param, int_param);
ints and a string) are optional.
Table 1. Data Type Overview
-Name Formating String Char C-Style Variable
-Integer d int
-Float f double
-String s char*
-String S str
-Optional modifier * marks all further parameters as optional
+ Name Formating String Char C-Style Variable
+ Integer d int
+ Float f double
+ String s char*
+ String S str
+ Optional modifier * marks all further parameters as optional
+ Autoconvert modifier . requires auto-conversion for the next parameter
1.2.3. Getting Parameters
@@ -278,17 +279,27 @@ Note
parameters to be retrieved. Each parameter is represented by exactly
one parameter type character in the string. The variable part of
parameters must contain as many pointers to C variables as there are
- formatting non-modifiers characters in the formatting string. The
- formatting string can also contain a "*" modifier that does not have a
- correspondent in the variable part of the parameters. The meaning of
- "*" is that any further parameters (defined by other type characters in
- the formatting string) are optional (they can be missing in the input
- and no rpc fault will automatically be generated).
+ formatting non-modifiers characters in the formatting string.
Warning
The function will crash if you fail to provide enough parameters.
+ Besides characters representing parameter types, the formatting string
+ can contain two special modifiers: "*" and ".". The modifiers do not
+ have a correspondent in the variable part of the parameters.
+
+ The meaning of "*" modifier is that any further parameters (defined by
+ other type characters in the formatting string) are optional (they can
+ be missing in the input and no rpc fault will automatically be
+ generated).
+
+ The '.' modifiers turns on type autoconversion for the next parameter.
+ This means that if the type of the next parameter differs from the type
+ specified in the formatting string, the parameter will be automatically
+ converted to the formatting string type (if possible) and if the
+ automatic conversion succeeds, no fault will be generated.
+
The function returns the number of parameters read on success (a number
greater or equal 0) and - (minus) the number of parameters read on
error (for example for an error after reading 2 parameters it will
@@ -297,8 +308,9 @@ Warning
number (- number of parameters read so far) and it will also
automatically change the reply that will be sent to the caller to
indicate that a failure has occurred on the server (unless the "*" is
- used and the error is lack of more parameters). The prototype of the
- function is:
+ used and the error is lack of more parameters).
+
+ The prototype of the function is:
int scan(char* fmt, ...)
It is possible to either call the function once to scan all the
@@ -368,6 +380,25 @@ static void rpc_delete_contact(rpc_t* rpc)
/* Process retrieved parameters here */
}
+/* variable number of parameters:
+ echo back all the parameters, string type required */
+static void core_prints(rpc_t* rpc, void* c)
+{
+ char* string = 0;
+ while((rpc->scan(c, "*s", &string)>0))
+ rpc->add(c, "s", string);
+}
+
+/* variable number of parameters and auto conversion:
+ echo back all the parameters, works with any type (everything is
+ internally converted to string, notice the '.' modifier) */
+static void core_echo(rpc_t* rpc, void* c)
+{
+ char* string = 0;
+ while((rpc->scan(c, "*.s", &string)>0))
+ rpc->add(c, "s", string);
+}
+
1.2.4. Building Reply
The RPC API contains several functions that can be used to modify
diff --git a/doc/rpc/ser_rpc.xml b/doc/rpc/ser_rpc.xml
index 5a20d8a..698bc9c 100644
--- a/doc/rpc/ser_rpc.xml
+++ b/doc/rpc/ser_rpc.xml
@@ -363,6 +363,11 @@ add("sd", string_param, int_param);
<entry>*</entry>
<entry>marks all further parameters as optional</entry>
</row>
+ <row>
+ <entry>Autoconvert modifier</entry>
+ <entry>.</entry>
+ <entry>requires auto-conversion for the next parameter</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -398,18 +403,34 @@ add("sd", string_param, int_param);
The variable part of parameters must contain as many pointers to C
variables as there are formatting non-modifiers characters in the
formatting string.
- The formatting string can also contain a "*" modifier that does not
- have a correspondent in the variable part of the parameters. The
- meaning of "*" is that any further parameters (defined by other
- type characters in the formatting string) are optional (they
- can be missing in the input and no rpc fault will automatically
- be generated).
<warning>
<para>
The function will crash if you fail to provide
enough parameters.
</para>
</warning>
+ </para>
+ <para>
+ Besides characters representing parameter types, the formatting
+ string can contain two special modifiers: "*" and ".". The
+ modifiers do not have a correspondent in the variable part of the
+ parameters.
+ </para>
+ <para>
+ The meaning of "*" modifier is that any further parameters
+ (defined by other type characters in the formatting string) are
+ optional (they can be missing in the input and no rpc fault will
+ automatically be generated).
+ </para>
+ <para>
+ The '.' modifiers turns on type autoconversion for the next
+ parameter. This means that if the type of the next parameter
+ differs from the type specified in the formatting string, the
+ parameter will be automatically converted to the formatting string
+ type (if possible) and if the automatic conversion succeeds, no
+ fault will be generated.
+ </para>
+ <para>
The function returns the number of parameters read on success
(a number greater or equal 0) and - (minus) the number of
parameters read on error (for example for an error after
@@ -420,7 +441,10 @@ add("sd", string_param, int_param);
and it will also automatically change the reply that will be
sent to the caller to indicate that a failure has occurred on
the server (unless the "*" is used and the error is lack
- of more parameters). The prototype of the function is:
+ of more parameters).
+ </para>
+ <para>
+ The prototype of the function is:
<programlisting>
int scan(char* fmt, ...)
</programlisting>
@@ -437,6 +461,8 @@ rpc->scan("d", &int_val);
rpc->scan("f", &double_val);
</programlisting>
</para>
+ <para>
+ </para>
</section>
<section>
<title><function>struct_scan</function></title>
@@ -506,6 +532,26 @@ static void rpc_delete_contact(rpc_t* rpc)
/* Process retrieved parameters here */
}
+
+/* variable number of parameters:
+ echo back all the parameters, string type required */
+static void core_prints(rpc_t* rpc, void* c)
+{
+ char* string = 0;
+ while((rpc->scan(c, "*s", &string)>0))
+ rpc->add(c, "s", string);
+}
+
+/* variable number of parameters and auto conversion:
+ echo back all the parameters, works with any type (everything is
+ internally converted to string, notice the '.' modifier) */
+static void core_echo(rpc_t* rpc, void* c)
+{
+ char* string = 0;
+ while((rpc->scan(c, "*.s", &string)>0))
+ rpc->add(c, "s", string);
+}
+
]]>
</programlisting>
</example>
More information about the sr-dev
mailing list