.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Frontier::Client 3pm"
.TH Frontier::Client 3pm "2021-01-03" "perl v5.32.0" "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::Client \- issue Frontier XML RPC requests to a server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Frontier::Client;
\&
\& $server = Frontier::Client\->new( I<OPTIONS> );
\&
\& $result = $server\->call($method, @args);
\&
\& $boolean = $server\->boolean($value);
\& $date_time = $server\->date_time($value);
\& $base64 = $server\->base64($value);
\&
\& $value = $boolean\->value;
\& $value = $date_time\->value;
\& $value = $base64\->value;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIFrontier::Client\fR is an XML-RPC client over \s-1HTTP.\s0
\&\fIFrontier::Client\fR instances are used to make calls to XML-RPC
servers and as shortcuts for creating XML-RPC special data types.
.SH "METHODS"
.IX Header "METHODS"
.IP "new( \fI\s-1OPTIONS\s0\fR )" 4
.IX Item "new( OPTIONS )"
Returns a new instance of \fIFrontier::Client\fR and associates it with
an XML-RPC server at a \s-1URL.\s0  \fI\s-1OPTIONS\s0\fR may be a list of key, value
pairs or a hash containing the following parameters:
.RS 4
.IP "url" 4
.IX Item "url"
The \s-1URL\s0 of the server.  This parameter is required.  For example:
.Sp
.Vb 1
\& $server = Frontier::Client\->new( \*(Aqurl\*(Aq => \*(Aqhttp://betty.userland.com/RPC2\*(Aq );
.Ve
.IP "proxy" 4
.IX Item "proxy"
A \s-1URL\s0 of a proxy to forward XML-RPC calls through.
.IP "encoding" 4
.IX Item "encoding"
The \s-1XML\s0 encoding to be specified in the \s-1XML\s0 declaration of outgoing
\&\s-1RPC\s0 requests.  Incoming results may have a different encoding
specified; XML::Parser will convert incoming data to \s-1UTF\-8.\s0  The
default outgoing encoding is none, which uses \s-1XML 1.0\s0's default of
\&\s-1UTF\-8.\s0  For example:
.Sp
.Vb 2
\& $server = Frontier::Client\->new( \*(Aqurl\*(Aq => \*(Aqhttp://betty.userland.com/RPC2\*(Aq,
\&                                  \*(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 <i4>,
<float>, and <string> values to objects instead of
scalars.  See \fBint()\fR, \fBfloat()\fR, and \fBstring()\fR below for more details.
.IP "debug" 4
.IX Item "debug"
If set to a non-zero value will print the encoded \s-1XML\s0 request and the
\&\s-1XML\s0 response received.
.RE
.RS 4
.RE
.ie n .IP "call($method, @args)" 4
.el .IP "call($method, \f(CW@args\fR)" 4
.IX Item "call($method, @args)"
Forward a procedure call to the server, either returning the value
returned by the procedure or failing with exception.  `\f(CW$method\fR' is
the name of the server method, and `\f(CW@args\fR' is a list of arguments
to pass.  Arguments may be Perl hashes, arrays, scalar values, or the
XML-RPC special data types below.
.ie n .IP "boolean( $value )" 4
.el .IP "boolean( \f(CW$value\fR )" 4
.IX Item "boolean( $value )"
.PD 0
.ie n .IP "date_time( $value )" 4
.el .IP "date_time( \f(CW$value\fR )" 4
.IX Item "date_time( $value )"
.ie n .IP "base64( $base64 )" 4
.el .IP "base64( \f(CW$base64\fR )" 4
.IX Item "base64( $base64 )"
.PD
The methods `\f(CW\*(C`boolean()\*(C'\fR', `\f(CW\*(C`date_time()\*(C'\fR', and `\f(CW\*(C`base64()\*(C'\fR' create
and return XML-RPC-specific datatypes that can be passed to
`\f(CW\*(C`call()\*(C'\fR'.  Results from servers may also contain 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
The value of boolean, date/time, and base64 data can be set or
returned using the `\f(CW\*(C`value()\*(C'\fR' method.  For example:
.Sp
.Vb 2
\&  # To set a value:
\&  $a_boolean\->value(1);
\&
\&  # To retrieve a value
\&  $base64 = $base64_xml_rpc_data\->value();
.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.
.IP "int( 42 );" 4
.IX Item "int( 42 );"
.PD 0
.IP "float( 3.14159 );" 4
.IX Item "float( 3.14159 );"
.ie n .IP "string( ""Foo"" );" 4
.el .IP "string( ``Foo'' );" 4
.IX Item "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 <i4> because it looks like an integer.  With these
methods, you could now create a string object like this:
.Sp
.Vb 1
\&  $part_num = $server\->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 \fBvalue()\fR as described
above.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBFrontier::RPC2\fR\|(3)
.PP
<http://www.scripting.com/frontier5/xml/code/rpc.html>
.SH "AUTHOR"
.IX Header "AUTHOR"
Ken MacLeod <ken@bitsko.slc.ut.us>