.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Frontier::RPC2 3pm" .TH Frontier::RPC2 3pm "2018-06-29" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Frontier::RPC2 \- encode/decode RPC2 format XML .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Frontier::RPC2; \& \& $coder = Frontier::RPC2\->new; \& \& $xml_string = $coder\->encode_call($method, @args); \& $xml_string = $coder\->encode_response($result); \& $xml_string = $coder\->encode_fault($code, $message); \& \& $call = $coder\->decode($xml_string); \& \& $response_xml = $coder\->serve($request_xml, $methods); \& \& $boolean_object = $coder\->boolean($boolean); \& $date_time_object = $coder\->date_time($date_time); \& $base64_object = $coder\->base64($base64); \& $int_object = $coder\->int(42); \& $float_object = $coder\->float(3.14159); \& $string_object = $coder\->string("Foo"); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIFrontier::RPC2\fR encodes and decodes \s-1XML RPC\s0 calls. .ie n .IP "$coder = Frontier::RPC2\->new( \fI\s-1OPTIONS\s0\fR )" 4 .el .IP "\f(CW$coder\fR = Frontier::RPC2\->new( \fI\s-1OPTIONS\s0\fR )" 4 .IX Item "$coder = Frontier::RPC2->new( OPTIONS )" Create a new encoder/decoder. The following option is supported: .RS 4 .IP "encoding" 4 .IX Item "encoding" The \s-1XML\s0 encoding to be specified in the \s-1XML\s0 declaration of encoded \s-1RPC\s0 requests or responses. Decoded results may have a different encoding specified; XML::Parser will convert decoded data to \s-1UTF\-8.\s0 The default encoding is none, which uses \s-1XML 1.0\s0's default of \s-1UTF\-8.\s0 For example: .Sp .Vb 1 \& $server = Frontier::RPC2\->new( \*(Aqencoding\*(Aq => \*(AqISO\-8859\-1\*(Aq ); .Ve .IP "use_objects" 4 .IX Item "use_objects" If set to a non-zero value will convert incoming , , and values to objects instead of scalars. See \fIint()\fR, \fIfloat()\fR, and \fIstring()\fR below for more details. .RE .RS 4 .RE .ie n .IP "$xml_string = $coder\->encode_call($method, @args)" 4 .el .IP "\f(CW$xml_string\fR = \f(CW$coder\fR\->encode_call($method, \f(CW@args\fR)" 4 .IX Item "$xml_string = $coder->encode_call($method, @args)" `\f(CW\*(C`encode_call\*(C'\fR' converts a method name and it's arguments into an \&\s-1RPC2\s0 `\f(CW\*(C`methodCall\*(C'\fR' element, returning the \s-1XML\s0 fragment. .ie n .IP "$xml_string = $coder\->encode_response($result)" 4 .el .IP "\f(CW$xml_string\fR = \f(CW$coder\fR\->encode_response($result)" 4 .IX Item "$xml_string = $coder->encode_response($result)" `\f(CW\*(C`encode_response\*(C'\fR' converts the return value of a procedure into an \&\s-1RPC2\s0 `\f(CW\*(C`methodResponse\*(C'\fR' element containing the result, returning the \&\s-1XML\s0 fragment. .ie n .IP "$xml_string = $coder\->encode_fault($code, $message)" 4 .el .IP "\f(CW$xml_string\fR = \f(CW$coder\fR\->encode_fault($code, \f(CW$message\fR)" 4 .IX Item "$xml_string = $coder->encode_fault($code, $message)" `\f(CW\*(C`encode_fault\*(C'\fR' converts a fault code and message into an \s-1RPC2\s0 `\f(CW\*(C`methodResponse\*(C'\fR' element containing a `\f(CW\*(C`fault\*(C'\fR' element, returning the \s-1XML\s0 fragment. .ie n .IP "$call = $coder\->decode($xml_string)" 4 .el .IP "\f(CW$call\fR = \f(CW$coder\fR\->decode($xml_string)" 4 .IX Item "$call = $coder->decode($xml_string)" `\f(CW\*(C`decode\*(C'\fR' converts an \s-1XML\s0 string containing an \s-1RPC2\s0 `\f(CW\*(C`methodCall\*(C'\fR' or `\f(CW\*(C`methodResponse\*(C'\fR' element into a hash containing three members, `\f(CW\*(C`type\*(C'\fR', `\f(CW\*(C`value\*(C'\fR', and `\f(CW\*(C`method_name\*(C'\fR'. `\f(CW\*(C`type\*(C'\fR' is one of `\f(CW\*(C`call\*(C'\fR', `\f(CW\*(C`response\*(C'\fR', or `\f(CW\*(C`fault\*(C'\fR'. `\f(CW\*(C`value\*(C'\fR' is array containing the parameters or result of the \s-1RPC.\s0 For a `\f(CW\*(C`call\*(C'\fR' type, `\f(CW\*(C`value\*(C'\fR' contains call's parameters and `\f(CW\*(C`method_name\*(C'\fR' contains the method being called. For a `\f(CW\*(C`response\*(C'\fR' type, the `\f(CW\*(C`value\*(C'\fR' array contains call's result. For a `\f(CW\*(C`fault\*(C'\fR' type, the `\f(CW\*(C`value\*(C'\fR' array contains a hash with the two members `\f(CW\*(C`faultCode\*(C'\fR' and `\f(CW\*(C`faultMessage\*(C'\fR'. .ie n .IP "$response_xml = $coder\->serve($request_xml, $methods)" 4 .el .IP "\f(CW$response_xml\fR = \f(CW$coder\fR\->serve($request_xml, \f(CW$methods\fR)" 4 .IX Item "$response_xml = $coder->serve($request_xml, $methods)" `\f(CW\*(C`serve\*(C'\fR' decodes `\f(CW$request_xml\fR', looks up the called method name in the `\f(CW$methods\fR' hash and calls it, and then encodes and returns the response as \s-1XML.\s0 .ie n .IP "$boolean_object = $coder\->boolean($boolean);" 4 .el .IP "\f(CW$boolean_object\fR = \f(CW$coder\fR\->boolean($boolean);" 4 .IX Item "$boolean_object = $coder->boolean($boolean);" .PD 0 .ie n .IP "$date_time_object = $coder\->date_time($date_time);" 4 .el .IP "\f(CW$date_time_object\fR = \f(CW$coder\fR\->date_time($date_time);" 4 .IX Item "$date_time_object = $coder->date_time($date_time);" .ie n .IP "$base64_object = $coder\->base64($base64);" 4 .el .IP "\f(CW$base64_object\fR = \f(CW$coder\fR\->base64($base64);" 4 .IX Item "$base64_object = $coder->base64($base64);" .PD These methods create and return XML-RPC-specific datatypes that can be passed to the encoder. The decoder may also return these datatypes. The corresponding package names (for use with `\f(CW\*(C`ref()\*(C'\fR', for example) are `\f(CW\*(C`Frontier::RPC2::Boolean\*(C'\fR', `\f(CW\*(C`Frontier::RPC2::DateTime::ISO8601\*(C'\fR', and `\f(CW\*(C`Frontier::RPC2::Base64\*(C'\fR'. .Sp You can change and retrieve the value of boolean, date/time, and base64 data using the `\f(CW\*(C`value\*(C'\fR' method of those objects, i.e.: .Sp .Vb 1 \& $boolean = $boolean_object\->value; \& \& $boolean_object\->value(1); .Ve .Sp Note: `\f(CW\*(C`base64()\*(C'\fR' does \fInot\fR encode or decode base64 data for you, you must use MIME::Base64 or similar module for that. .ie n .IP "$int_object = $coder\->int(42);" 4 .el .IP "\f(CW$int_object\fR = \f(CW$coder\fR\->int(42);" 4 .IX Item "$int_object = $coder->int(42);" .PD 0 .ie n .IP "$float_object = $coder\->float(3.14159);" 4 .el .IP "\f(CW$float_object\fR = \f(CW$coder\fR\->float(3.14159);" 4 .IX Item "$float_object = $coder->float(3.14159);" .ie n .IP "$string_object = $coder\->string(""Foo"");" 4 .el .IP "\f(CW$string_object\fR = \f(CW$coder\fR\->string(``Foo'');" 4 .IX Item "$string_object = $coder->string(Foo);" .PD By default, you may pass ordinary Perl values (scalars) to be encoded. \&\s-1RPC2\s0 automatically converts them to XML-RPC types if they look like an integer, float, or as a string. This assumption causes problems when you want to pass a string that looks like \*(L"0096\*(R", \s-1RPC2\s0 will convert that to an because it looks like an integer. With these methods, you could now create a string object like this: .Sp .Vb 1 \& $part_num = $coder\->string("0096"); .Ve .Sp and be confident that it will be passed as an XML-RPC string. You can change and retrieve values from objects using \fIvalue()\fR as described above. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIperl\fR\|(1), \fIFrontier::Daemon\fR\|(3), \fIFrontier::Client\fR\|(3) .PP .SH "AUTHOR" .IX Header "AUTHOR" Ken MacLeod