[sr-dev] git:master: doc: rpc api documentation updated: the '.' modifier

Module: sip-router Branch: master Commit: 46fb4917c2163fd5c8bd01fdd866813211cd6ec7 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=46fb491… Author: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Committer: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; 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", &amp;int_val); rpc->scan("f", &amp;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>