.\" Automatically generated by Pod::Man 4.10 (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
..
.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 "POE::Component::Server::JSONRPC 3pm"
.TH POE::Component::Server::JSONRPC 3pm "2019-01-06" "perl v5.28.1" "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"
POE::Component::Server::JSONRPC \- POE tcp or http based JSON\-RPC server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    #http version:
\&    POE::Component::Server::JSONRPC::Http\->new(
\&        # consider using something like JSON::MaybeXS for better performance
\&        json    => JSON::MaybeXS\->new\->utf8\->allow_nonref,
\&        Port    => 3000,
\&        Handler => {
\&            \*(Aqecho\*(Aq => \*(Aqecho\*(Aq,
\&            \*(Aqsum\*(Aq  => \*(Aqsum\*(Aq,
\&        },
\&        SslKey  => \*(Aq/path/to/the/server.key\*(Aq,
\&        SslCert => \*(Aq/path/to/the/server.crt\*(Aq,
\&        Authenticate => \e&authentication_handler,
\&        # authentication_handler must be a function that takes two parameters login and password,
\&        # and returns true if connection is successful, false otherwise
\&    );
\&
\&    #tcp version:
\&    POE::Component::Server::JSONRPC::Tcp\->new(
\&        Port    => 3000,
\&        Handler => {
\&            \*(Aqecho\*(Aq => \*(Aqecho\*(Aq,
\&            \*(Aqsum\*(Aq  => \*(Aqsum\*(Aq,
\&        },
\&    );
\&
\&    sub echo {
\&        my ($kernel, $jsonrpc, $id, @params) = @_[KERNEL, ARG0..$#_ ];
\&
\&        $kernel\->post( $jsonrpc => \*(Aqresult\*(Aq => $id, @params );
\&    }
\&
\&    sub sum {
\&        my ($kernel, $jsonrpc, $id, @params) = @_[KERNEL, ARG0..$#_ ];
\&
\&        $kernel\->post( $jsonrpc => \*(Aqresult\*(Aq => $id, $params[0] + $params[1] );
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a \s-1POE\s0 component for tcp or http based JSON-RPC Server.
.PP
The specification is defined on http://json\-rpc.org/ and this module use JSON-RPC 1.0 spec (1.1 does not cover tcp streams)
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Create \s-1JSONRPC\s0 component session and return the session id.
.PP
Parameters:
.IP "Port" 4
.IX Item "Port"
Port number for listen.
.IP "Handler" 4
.IX Item "Handler"
Hash variable contains handler name as key, handler poe state name as value.
.Sp
Handler name (key) is used as JSON-RPC method name.
.Sp
So if you send {\*(L"method\*(R":\*(L"echo\*(R"}, this module call the poe state named \*(L"echo\*(R".
.SH "HANDLER PARAMETERS"
.IX Header "HANDLER PARAMETERS"
.IP "\s-1ARG0\s0" 4
.IX Item "ARG0"
A session id of PoCo::Server::JSONRPC itself.
.IP "\s-1ARG1\s0" 4
.IX Item "ARG1"
The id of the client you're treating, send that back in result/error.
.IP "\s-1ARG2 .. ARGN\s0" 4
.IX Item "ARG2 .. ARGN"
\&\s-1JSONRPC\s0 argguments
.PP
ex) If you send following request
.PP
.Vb 1
\&    {"method":"echo", "params":["foo", "bar"]}
.Ve
.PP
then, \*(L"echo\*(R" handler is called and parameters is that \s-1ARG0\s0 is component session id, \s-1ARG1\s0 is client id, \s-1ARG2\s0 \*(L"foo\*(R", \s-1ARG3\s0 \*(L"bar\*(R".
.SH "HANDLER RESPONSE"
.IX Header "HANDLER RESPONSE"
You must call either \*(L"result\*(R" or \*(L"error\*(R" state in your handlers to response result or error.
.PP
ex:
.PP
.Vb 1
\&   $kernel\->post( $component_session_id => "result" => $client_id, "result value" )
.Ve
.PP
\&\f(CW$component_session_id\fR is \s-1ARG0\s0 in handler. If you do above, response is:
.PP
.Vb 1
\&   {"result":"result value", "error":""}
.Ve
.SH "POE METHODS"
.IX Header "POE METHODS"
Inner method for \s-1POE\s0 states.
.SS "poe_\|_start"
.IX Subsection "poe__start"
.SS "poe_init_server"
.IX Subsection "poe_init_server"
Should be defined in Http or Tcp
.SS "poe_input_handler"
.IX Subsection "poe_input_handler"
.SS "poe_result"
.IX Subsection "poe_result"
.SS "poe_error"
.IX Subsection "poe_error"
.SS "poe_send"
.IX Subsection "poe_send"
Should be defined in Http or Tcp
.PP
Côme Chilliet <mcmic@cpan.org>
Daisuke Murase <typester@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.