ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Handle.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.238 by root, Tue Dec 10 15:54:51 2013 UTC vs.
Revision 1.241 by root, Fri Sep 5 22:17:26 2014 UTC

… …
496callback. 496callback.
497 497
498This callback will only be called on TLS shutdowns, not when the 498This callback will only be called on TLS shutdowns, not when the
499underlying handle signals EOF. 499underlying handle signals EOF.
500 500
501=item json => L<JSON> or L<JSON::XS> object 501=item json => L<JSON>, L<JSON::PP> or L<JSON::XS> object
502 502
503This is the json coder object used by the C<json> read and write types. 503This is the json coder object used by the C<json> read and write types.
504 504
505If you don't supply it, then AnyEvent::Handle will create and use a 505If you don't supply it, then AnyEvent::Handle will create and use a
506suitable one (on demand), which will write and expect UTF-8 encoded JSON 506suitable one (on demand), which will write and expect UTF-8 encoded
507JSON texts (either using L<JSON::XS> or L<JSON>). The written texts are
508guaranteed not to contain any newline character.
509
510For security reasons, this encoder will likely I<not> handle numbers and
511strings, only arrays and objects/hashes. The reason is that originally
512JSON was self-delimited, but Dougles Crockford thought it was a splendid
513idea to redefine JSON incompatibly, so this is no longer true.
514
515For protocols that used back-to-back JSON texts, this might lead to
516run-ins, where two or more JSON texts will be interpreted as one JSON
507texts. 517text.
508 518
509Note that you are responsible to depend on the L<JSON> module if you want 519For this reason, if the default encoder uses L<JSON::XS>, it will default
510to use this functionality, as AnyEvent does not have a dependency on it 520to not allowing anything but arrays and objects/hashes, at least for the
511itself. 521forseeable future (it will change at some point). This might or might not
522be true for the L<JSON> module, so this might cause a security issue.
523
524If you depend on either behaviour, you should create your own json object
525and pass it in explicitly.
512 526
513=item cbor => L<CBOR::XS> object 527=item cbor => L<CBOR::XS> object
514 528
515This is the cbor coder object used by the C<cbor> read and write types. 529This is the cbor coder object used by the C<cbor> read and write types.
516 530
517If you don't supply it, then AnyEvent::Handle will create and use a 531If you don't supply it, then AnyEvent::Handle will create and use a
518suitable one (on demand), which will write CBOR without using extensions, 532suitable one (on demand), which will write CBOR without using extensions,
519if possible. texts. 533if possible.
520 534
521Note that you are responsible to depend on the L<CBOR::XS> module if you 535Note that you are responsible to depend on the L<CBOR::XS> module if you
522want to use this functionality, as AnyEvent does not have a dependency on 536want to use this functionality, as AnyEvent does not have a dependency on
523it itself. 537it itself.
524 538
… …
1058 1072
1059Encodes the given hash or array reference into a JSON object. Unless you 1073Encodes the given hash or array reference into a JSON object. Unless you
1060provide your own JSON object, this means it will be encoded to JSON text 1074provide your own JSON object, this means it will be encoded to JSON text
1061in UTF-8. 1075in UTF-8.
1062 1076
1077The default encoder might or might not handle every type of JSON value -
1078it might be limited to arrays and objects for security reasons. See the
1079C<json> constructor attribute for more details.
1080
1063JSON objects (and arrays) are self-delimiting, so you can write JSON at 1081JSON objects (and arrays) are self-delimiting, so if you only use arrays
1064one end of a handle and read them at the other end without using any 1082and hashes, you can write JSON at one end of a handle and read them at the
1065additional framing. 1083other end without using any additional framing.
1066 1084
1067The generated JSON text is guaranteed not to contain any newlines: While 1085The JSON text generated by the default encoder is guaranteed not to
1068this module doesn't need delimiters after or between JSON texts to be 1086contain any newlines: While this module doesn't need delimiters after or
1069able to read them, many other languages depend on that. 1087between JSON texts to be able to read them, many other languages depend on
1088them.
1070 1089
1071A simple RPC protocol that interoperates easily with other languages is 1090A simple RPC protocol that interoperates easily with other languages is
1072to send JSON arrays (or objects, although arrays are usually the better 1091to send JSON arrays (or objects, although arrays are usually the better
1073choice as they mimic how function argument passing works) and a newline 1092choice as they mimic how function argument passing works) and a newline
1074after each JSON text: 1093after each JSON text:
… …
1106 1125
1107=cut 1126=cut
1108 1127
1109sub json_coder() { 1128sub json_coder() {
1110 eval { require JSON::XS; JSON::XS->new->utf8 } 1129 eval { require JSON::XS; JSON::XS->new->utf8 }
1111 || do { require JSON; JSON->new->utf8 } 1130 || do { require JSON::PP; JSON::PP->new->utf8 }
1112} 1131}
1113 1132
1114register_write_type json => sub { 1133register_write_type json => sub {
1115 my ($self, $ref) = @_; 1134 my ($self, $ref) = @_;
1116 1135
… …
1708=item json => $cb->($handle, $hash_or_arrayref) 1727=item json => $cb->($handle, $hash_or_arrayref)
1709 1728
1710Reads a JSON object or array, decodes it and passes it to the 1729Reads a JSON object or array, decodes it and passes it to the
1711callback. When a parse error occurs, an C<EBADMSG> error will be raised. 1730callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1712 1731
1713If a C<json> object was passed to the constructor, then that will be used 1732If a C<json> object was passed to the constructor, then that will be
1714for the final decode, otherwise it will create a JSON coder expecting UTF-8. 1733used for the final decode, otherwise it will create a L<JSON::XS> or
1734L<JSON::PP> coder object expecting UTF-8.
1715 1735
1716This read type uses the incremental parser available with JSON version 1736This read type uses the incremental parser available with JSON version
17172.09 (and JSON::XS version 2.2) and above. You have to provide a 17372.09 (and JSON::XS version 2.2) and above.
1718dependency on your own: this module will load the JSON module, but
1719AnyEvent does not depend on it itself.
1720 1738
1721Since JSON texts are fully self-delimiting, the C<json> read and write 1739Since JSON texts are fully self-delimiting, the C<json> read and write
1722types are an ideal simple RPC protocol: just exchange JSON datagrams. See 1740types are an ideal simple RPC protocol: just exchange JSON datagrams. See
1723the C<json> write type description, above, for an actual example. 1741the C<json> write type description, above, for an actual example.
1724 1742
… …
2063sub _dotls { 2081sub _dotls {
2064 my ($self) = @_; 2082 my ($self) = @_;
2065 2083
2066 my $tmp; 2084 my $tmp;
2067 2085
2068 if (length $self->{_tls_wbuf}) { 2086 while (length $self->{_tls_wbuf}) {
2069 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 2087 if (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) <= 0) {
2070 substr $self->{_tls_wbuf}, 0, $tmp, ""; 2088 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
2089
2090 return $self->_tls_error ($tmp)
2091 if $tmp != $ERROR_WANT_READ
2092 && ($tmp != $ERROR_SYSCALL || $!);
2093
2094 last;
2071 } 2095 }
2072 2096
2073 $tmp = Net::SSLeay::get_error ($self->{tls}, $tmp); 2097 substr $self->{_tls_wbuf}, 0, $tmp, "";
2074 return $self->_tls_error ($tmp)
2075 if $tmp != $ERROR_WANT_READ
2076 && ($tmp != $ERROR_SYSCALL || $!);
2077 } 2098 }
2078 2099
2079 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) { 2100 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
2080 unless (length $tmp) { 2101 unless (length $tmp) {
2081 $self->{_on_starttls} 2102 $self->{_on_starttls}
… …
2095 $self->{_tls_rbuf} .= $tmp; 2116 $self->{_tls_rbuf} .= $tmp;
2096 $self->_drain_rbuf; 2117 $self->_drain_rbuf;
2097 $self->{tls} or return; # tls session might have gone away in callback 2118 $self->{tls} or return; # tls session might have gone away in callback
2098 } 2119 }
2099 2120
2100 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); 2121 $tmp = Net::SSLeay::get_error ($self->{tls}, -1); # -1 is not neccessarily correct, but Net::SSLeay doesn't tell us
2101 return $self->_tls_error ($tmp) 2122 return $self->_tls_error ($tmp)
2102 if $tmp != $ERROR_WANT_READ 2123 if $tmp != $ERROR_WANT_READ
2103 && ($tmp != $ERROR_SYSCALL || $!); 2124 && ($tmp != $ERROR_SYSCALL || $!);
2104 2125
2105 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) { 2126 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines