view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    CLOSE

              This event accepts only one argument: the HTTP::Response object we sent to the handler.
      
              Calling this event will close the socket, not sending any output

    GETHANDLERS

              This event accepts 2 arguments: The session + event to send the response to
      
              This event will send back the current HANDLERS array ( deep-cloned via Storable::dclone )
      
              The resulting array can be played around to your tastes, then once you are done...

    SETHANDLERS

              This event accepts only one argument: pointer to HANDLERS array
      
              BEWARE: if there is an error in the HANDLERS, SimpleHTTP will die!

    SETCLOSEHANDLER

          $_[KERNEL]->call( $_[SENDER], 'SETCLOSEHANDLER', $connection,
                            $event, @args );

      Calls $event in the current session when $connection is closed. You
      could use for persistent connection handling.

      Multiple session may register close handlers.

      Calling SETCLOSEHANDLER without $event to remove the current
      session's handler:

         $_[KERNEL]->call( $_[SENDER], 'SETCLOSEHANDLER', $connection );

      You must make sure that @args doesn't cause a circular reference.
      Ideally, use $connection-ID> or some other unique value associated
      with this $connection.

    STARTLISTEN

              Starts the listening socket, if it was shut down

    STOPLISTEN

              Simply a wrapper for SHUTDOWN GRACEFUL, but will not shutdown SimpleHTTP if there is no more requests

    SHUTDOWN

              Without arguments, SimpleHTTP does this:
                      Close the listening socket
                      Kills all pending requests by closing their sockets
                      Removes it's alias
      
              With an argument of 'GRACEFUL', SimpleHTTP does this:
                      Close the listening socket
                      Waits for all pending requests to come in via DONE/CLOSE, then removes it's alias

    STREAM

              With a $response argument it streams the content and calls back the streaming event
              of the user's session (or with the dont_flush option you're responsible for calling
              back your session's streaming event).
      
              To use the streaming feature see below.

 Streaming with SimpleHTTP

    It's possible to send data as a stream to clients (unbuffered and
    integrated in the POE loop).

    Just create your session to receive events from SimpleHTTP as usually
    and add a streaming event, this event will be triggered over and over
    each time you set the $response to a streaming state and once you
    trigger it:

       # sets the response as streamed within our session which alias is HTTP_GET
       # with the event GOT_STREAM
       $response->stream(
          session     => 'HTTP_GET',
          event       => 'GOT_STREAM',
          dont_flush  => 1
       );
    
       # then you can simply yield your streaming event, once the GOT_STREAM event
       # has reached its end it will be triggered again and again, until you
       # send a CLOSE event to the kernel with the appropriate response as parameter
       $kernel->yield('GOT_STREAM', $response);

    The optional dont_flush option gives the user the ability to control
    the callback to the streaming event, which means once your stream event
    has reached its end it won't be called, you have to call it back.

    You can now send data by chunks and either call yourself back (via POE)
    or shutdown when your streaming is done (EOF for example).

       sub GOT_STREAM {
          my ( $kernel, $heap, $response ) = @_[KERNEL, HEAP, ARG0];
    
          # sets the content of the response
          $response->content("Hello World\n");
    
          # send it to the client
          POE::Kernel->post('HTTPD', 'STREAM', $response);
    
          # if we have previously set the dont_flush option
          # we have to trigger our event back until the end of
          # the stream like this (that can be a yield, of course):
          #
          # $kernel->delay('GOT_STREAM', 1, $stream );
    
          # otherwise the GOT_STREAM event is triggered continuously until
          # we call the CLOSE event on the response like that :
          #
          if ($heap{'streaming_is_done'}) {
             # close the socket and end the stream
             POE::Kernel->post('HTTPD', 'CLOSE', $response );
          }
       }

    The dont_flush option is there to be able to control the frequency of
    flushes to the client.

 SimpleHTTP Notes

    You can enable debugging mode by doing this:

            sub POE::Component::Server::SimpleHTTP::DEBUG () { 1 }
            use POE::Component::Server::SimpleHTTP;

    Also, this module will try to keep the Listening socket alive. if it
    dies, it will open it again for a max of 5 retries.

    You can override this behavior by doing this:

            sub POE::Component::Server::SimpleHTTP::MAX_RETRIES () { 10 }
            use POE::Component::Server::SimpleHTTP;

    For those who are pondering about basic-authentication, here's a tiny
    snippet to put in the Event handler

            # Contributed by Rocco Caputo
            sub Got_Request {
                    # ARG0 = HTTP::Request, ARG1 = HTTP::Response
                    my( $request, $response ) = @_[ ARG0, ARG1 ];
    
                    # Get the login
                    my ( $login, $password ) = $request->authorization_basic();
    
                    # Decide what to do
                    if ( ! defined $login or ! defined $password ) {
                            # Set the authorization
                            $response->header( 'WWW-Authenticate' => 'Basic realm="MyRealm"' );
                            $response->code( 401 );
                            $response->content( 'FORBIDDEN.' );
    
                            # Send it off!
                            $_[KERNEL]->post( 'SimpleHTTP', 'DONE', $response );
                    } else {
                            # Authenticate the user and move on
                    }
            }

 EXPORT

    Nothing.

ABSTRACT

            An easy to use HTTP daemon for POE-enabled programs

SEE ALSO

            L<POE>