# Net::HTTP (Class)

In: | net/http.rb
Parent: | Protocol

for backward compatibility

## Methods

Proxy active? default_port finish get get get2 get_print get_response head head2 inspect is_version_1_1? is_version_1_2? new new post post2 proxy? proxy_address proxy_class? proxy_pass proxy_port proxy_user proxyaddr proxyport read_timeout= request request_get request_head request_post send_request set_debug_output start start started? version_1_1 version_1_1? version_1_2 version_1_2?

## Constants

ProxyMod | = | ProxyDelta

## External Aliases

new -> newobj
request_put -> put2

## Attributes

address | [R] | The host name to connect to.
close_on_empty_response | [RW] |
open_timeout | [RW] | Seconds to wait until connection is opened. If the HTTP object cannot open a conection in this many seconds, it raises a TimeoutError exception.
port | [R] | The port number to connect to.
proxy_address | [R] |
proxy_pass | [R] |
proxy_port | [R] |
proxy_user | [R] |
read_timeout | [R] | Seconds to wait until reading one block (by one read(2) call). If the HTTP object cannot open a conection in this many seconds, it raises a TimeoutError exception.

## Classes and Modules

Class Net::HTTP::Get
Class Net::HTTP::Head
Class Net::HTTP::Post
Class Net::HTTP::Put

## Public Class methods

version_1_2()

Turns on net/http 1.2 (ruby 1.8) features. Defaults to ON in ruby 1.8.

I strongly recommend to call this method always.

      require 'net/http'
      Net::HTTP.version_1_2

[Source]

    # File net/http.rb, line 189
        def HTTP.version_1_2
          @@newimpl = true
        end

version_1_1()

Turns on net/http 1.1 (ruby 1.6) features. Defaults to OFF in ruby 1.8.

[Source]

    # File net/http.rb, line 195
        def HTTP.version_1_1
          @@newimpl = false
        end

version_1_2?()

true if net/http is in version 1.2 mode. Defaults to true.

[Source]

    # File net/http.rb, line 201
        def HTTP.version_1_2?
          @@newimpl
        end

version_1_1?()

true if net/http is in version 1.1 compatible mode. Defaults to true.

[Source]

    # File net/http.rb, line 207
        def HTTP.version_1_1?
          not @@newimpl
        end

is_version_1_1?()

Alias for version_1_1?

is_version_1_2?()

Alias for version_1_2?

get_print( arg1, arg2 = nil, port = nil )

Get body from target and output it to +$stdout+. The target can either be specified as (`uri`), or as (`host`, `path`, `port` = 80); so:

       Net::HTTP.get_print URI.parse('http://www.example.com/index.html')

or:

       Net::HTTP.get_print('www.example.com', '/index.html')

[Source]

    # File net/http.rb, line 237
        def HTTP.get_print( arg1, arg2 = nil, port = nil )
          if arg2
            addr, path = arg1, arg2
          else
            uri = arg1
            addr = uri.host
            path = uri.request_uri
            port = uri.port
          end
          new(addr, port || HTTP.default_port).start {|http|
            http.get path, nil, $stdout
          }
          nil
        end

get( arg1, arg2 = nil, arg3 = nil )

Send a GET request to the target and return the response as a string. The target can either be specified as (`uri`), or as (`host`, `path`, `port` = 80); so:

       print Net::HTTP.get(URI.parse('http://www.example.com/index.html'))

or:

       print Net::HTTP.get('www.example.com', '/index.html')

[Source]

    # File net/http.rb, line 262
        def HTTP.get( arg1, arg2 = nil, arg3 = nil )
          get_response(arg1,arg2,arg3).body
        end

get_response( arg1, arg2 = nil, arg3 = nil )

Send a GET request to the target and return the response as a Net::HTTPResponse object. The target can either be specified as (`uri`), or as (`host`, `path`, `port` = 80); so:

       res = Net::HTTP.get_response(URI.parse('http://www.example.com/index.html'))
       print res.body

or:

       res = Net::HTTP.get_response('www.example.com', '/index.html')
       print res.body

[Source]

    # File net/http.rb, line 278
        def HTTP.get_response( arg1, arg2 = nil, arg3 = nil )
          if arg2
            get_by_path(arg1, arg2, arg3)
          else
            get_by_uri(arg1)
          end
        end

default_port()

The default port to use for HTTP requests; defaults to 80.

[Source]

    # File net/http.rb, line 307
        def HTTP.default_port
          80
        end

start( address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil ) {|+http+| ...}

creates a new Net::HTTP object and opens its TCP connection and HTTP session. If the optional block is given, the newly created Net::HTTP object is passed to it and closed when the block finishes. In this case, the return value of this method is the return value of the block. If no block is given, the return value of this method is the newly created Net::HTTP object itself, and the caller is responsible for closing it upon completion.

[Source]

    # File net/http.rb, line 323
          def start( address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil, &block ) # :yield: +http+

            new(address, port, p_addr, p_port, p_user, p_pass).start(&block)
          end

new( address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil )

Creates a new Net::HTTP object. If `proxy_addr` is given, creates an Net::HTTP object with proxy support. This method does not open the TCP connection.

[Source]

    # File net/http.rb, line 332
          def new( address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil )
            obj = Proxy(p_addr, p_port, p_user, p_pass).newobj(address, port)
            setimplversion obj
            obj
          end

new( address, port = nil )

Creates a new Net::HTTP object for the specified `address`. This method does not open the TCP connection.

[Source]

    # File net/http.rb, line 341
        def initialize( address, port = nil )
          @address = address
          @port    = port || HTTP.default_port

          @curr_http_version = HTTPVersion
          @seems_1_0_server = false
          @close_on_empty_response = false
          @socket  = nil
          @started = false

          @open_timeout = 30
          @read_timeout = 60

          @debug_output = nil
        end

Proxy( p_addr, p_port = nil, p_user = nil, p_pass = nil )

Creates an HTTP proxy class. Arguments are address/port of proxy host and username/password if authorization on proxy server is required. You can replace the HTTP class with created proxy class.

If ADDRESS is nil, this method returns self (Net::HTTP).

        # Example
        proxy_class = Net::HTTP::Proxy('proxy.example.com', 8080)
                        :
        proxy_class.start('www.ruby-lang.org') {|http|
          # connecting proxy.foo.org:8080
                        :
        }

[Source]

    # File net/http.rb, line 484
        def HTTP.Proxy( p_addr, p_port = nil, p_user = nil, p_pass = nil )
          return self unless p_addr

          delta = ProxyDelta
          proxyclass = Class.new(self)
          proxyclass.module_eval {
            include delta
            # with proxy

            @is_proxy_class = true
            @proxy_address = p_addr
            @proxy_port    = p_port || default_port()
            @proxy_user    = p_user
            @proxy_pass    = p_pass
          }
          proxyclass
        end

proxy_class?()

returns true if self is a class which was created by HTTP::Proxy.

[Source]

    # File net/http.rb, line 503
          def proxy_class?
            @is_proxy_class
          end

## Public Instance methods

inspect()

[Source]

    # File net/http.rb, line 357
        def inspect
          "#<#{self.class} #{@address}:#{@port} open=#{started?}>"
        end

set_debug_output( output )

WARNING This method causes serious security hole. Never use this method in production code.

Set an output stream for debugging.

      http = Net::HTTP.new
      http.set_debug_output $stderr
      http.start { .... }

[Source]

    # File net/http.rb, line 370
        def set_debug_output( output )
          warn 'Net::HTTP#set_debug_output called after HTTP started' if started?
          @debug_output = output
        end

read_timeout=( sec )

Setter for the read_timeout attribute.

[Source]

    # File net/http.rb, line 392
        def read_timeout=( sec )
          @socket.read_timeout = sec if @socket
          @read_timeout = sec
        end

started?()

returns true if the HTTP session is started.

[Source]

    # File net/http.rb, line 398
        def started?
          @started
        end

active?()

Alias for started?

start() {|http| ...}

Opens TCP connection and HTTP session.

When this method is called with block, gives a HTTP object to the block and closes the TCP connection / HTTP session after the block executed.

When called with a block, returns the return value of the block; otherwise, returns self.

[Source]

    # File net/http.rb, line 415
        def start  # :yield: http

          raise IOError, 'HTTP session already opened' if @started
          if block_given?
            begin
              do_start
              return yield(self)
            ensure
              do_finish
            end
          end
          do_start
          self
        end

finish()

Finishes HTTP session and closes TCP connection. Raises IOError if not started.

[Source]

    # File net/http.rb, line 444
        def finish
          raise IOError, 'HTTP session not started yet' unless started?
          do_finish
        end

proxy?()

True if self is a HTTP proxy class

[Source]

    # File net/http.rb, line 514
        def proxy?
          self.class.proxy_class?
        end

proxy_address()

Address of proxy host. If self does not use a proxy, nil.

[Source]

    # File net/http.rb, line 519
        def proxy_address
          self.class.proxy_address
        end

proxy_port()

Port number of proxy host. If self does not use a proxy, nil.

[Source]

    # File net/http.rb, line 524
        def proxy_port
          self.class.proxy_port
        end

proxy_user()

User name for accessing proxy. If self does not use a proxy, nil.

[Source]

    # File net/http.rb, line 529
        def proxy_user
          self.class.proxy_user
        end

proxy_pass()

User password for accessing proxy. If self does not use a proxy, nil.

[Source]

    # File net/http.rb, line 534
        def proxy_pass
          self.class.proxy_pass
        end

proxyaddr()

Alias for proxy_address

proxyport()

Alias for proxy_port

get( path, initheader = nil, dest = nil ) {|+body_segment+| ...}

Gets data from `path` on the connected-to host. `header` must be a Hash like { ‘Accept’ => ’*/*’, … }.

In version 1.1 (ruby 1.6), this method returns a pair of objects, a Net::HTTPResponse object and the entity body string. In version 1.2 (ruby 1.8), this method returns a Net::HTTPResponse object.

If called with a block, yields each fragment of the entity body in turn as a string as it is read from the socket. Note that in this case, the returned response object will not contain a (meaningful) body.

`dest` argument is obsolete. It still works but you must not use it.

In version 1.1, this method might raise an exception for 3xx (redirect). In this case you can get a HTTPResponse object by "anException.response".

In version 1.2, this method never raises exception.

        # version 1.1 (bundled with Ruby 1.6)
        response, body = http.get('/index.html')

        # version 1.2 (bundled with Ruby 1.8 or later)
        response = http.get('/index.html')

        # using block
        File.open('result.txt', 'w') {|f|
          http.get('/~foo/') do |str|
            f.write str
          end
        }

[Source]

    # File net/http.rb, line 616
        def get( path, initheader = nil, dest = nil, &block ) # :yield: +body_segment+

          res = nil
          request(Get.new(path, initheader)) {|r|
            r.read_body dest, &block
            res = r
          }
          unless @newimpl
            res.value
            return res, res.body
          end

          res
        end

head( path, initheader = nil )

Gets only the header from `path` on the connected-to host. `header` is a Hash like { ‘Accept’ => ’*/*’, … }.

This method returns a Net::HTTPResponse object.

In version 1.1, this method might raise an exception for 3xx (redirect). On the case you can get a HTTPResponse object by "anException.response". In version 1.2, this method never raises an exception.

        response = nil
        Net::HTTP.start('some.www.server', 80) {|http|
          response = http.head('/index.html')
        }
        p response['content-type']

[Source]

    # File net/http.rb, line 646
        def head( path, initheader = nil )
          res = request(Head.new(path, initheader))
          res.value unless @newimpl
          res
        end

post( path, data, initheader = nil, dest = nil ) {|+body_segment+| ...}

Posts `data` (must be a String) to `path`. `header` must be a Hash like { ‘Accept’ => ’*/*’, … }.

In version 1.1 (ruby 1.6), this method returns a pair of objects, a Net::HTTPResponse object and an entity body string. In version 1.2 (ruby 1.8), this method returns a Net::HTTPReponse object.

If called with a block, yields each fragment of the entity body in turn as a string as it are read from the socket. Note that in this case, the returned response object will not contain a (meaningful) body.

`dest` is an alternative method of collecting the body. It must be an object responding to the "<<" operator (such as a String or an Array). Each fragment of the entity body will be "<<"-ed in turn onto `dest` if provided, and it will also become the body of the returned response object.

You must not provide both `dest` and a block; doing so will result in an ArgumentError.

In version 1.1, this method might raise an exception for 3xx (redirect). In this case you can get an HTTPResponse object by "anException.response". In version 1.2, this method never raises exception.

        # version 1.1
        response, body = http.post('/cgi-bin/search.rb', 'query=foo')

        # version 1.2
        response = http.post('/cgi-bin/search.rb', 'query=foo')

        # using block
        File.open('result.txt', 'w') {|f|
          http.post('/cgi-bin/search.rb', 'query=foo') do |str|
            f.write str
          end
        }

[Source]

    # File net/http.rb, line 690
        def post( path, data, initheader = nil, dest = nil, &block ) # :yield: +body_segment+

          res = nil
          request(Post.new(path, initheader), data) {|r|
            r.read_body dest, &block
            res = r
          }
          unless @newimpl
            res.value
            return res, res.body
          end

          res
        end

request_get( path, initheader = nil ) {|+response+| ...}

Sends a GET request to the `path` and gets a response, as an HTTPResponse object.

When called with a block, yields an HTTPResponse object. The body of this response will not have been read yet; the caller can process it using HTTPResponse#read_body, if desired.

Returns the response.

This method never raises Net::* exceptions.

        response = http.request_get('/index.html')
        # The entity body is already read here.
        p response['content-type']
        puts response.body

        # using block
        http.request_get('/index.html') {|response|
          p response['content-type']
          response.read_body do |str|   # read body now
            print str
          end
        }

[Source]

    # File net/http.rb, line 735
        def request_get( path, initheader = nil, &block ) # :yield: +response+

          request Get.new(path, initheader), &block
        end

request_head( path, initheader = nil, &block )

Sends a HEAD request to the `path` and gets a response, as an HTTPResponse object.

Returns the response.

This method never raises Net::* exceptions.

        response = http.request_head('/index.html')
        p response['content-type']

[Source]

    # File net/http.rb, line 749
        def request_head( path, initheader = nil, &block )
          request Head.new(path, initheader), &block
        end

request_post( path, data, initheader = nil ) {|+response+| ...}

Sends a POST request to the `path` and gets a response, as an HTTPResponse object.

When called with a block, yields an HTTPResponse object. The body of this response will not have been read yet; the caller can process it using HTTPResponse#read_body, if desired.

Returns the response.

This method never raises Net::* exceptions.

        # example
        response = http.request_post('/cgi-bin/nice.rb', 'datadatadata...')
        p response.status
        puts response.body          # body is already read

        # using block
        http.request_post('/cgi-bin/nice.rb', 'datadatadata...') {|response|
          p response.status
          p response['content-type']
          response.read_body do |str|   # read body now
            print str
          end
        }

[Source]

    # File net/http.rb, line 778
        def request_post( path, data, initheader = nil, &block ) # :yield: +response+

          request Post.new(path, initheader), data, &block
        end

get2( path, initheader = nil )

Alias for request_get

head2( path, initheader = nil, &block )

Alias for request_head

post2( path, data, initheader = nil )

Alias for request_post

send_request( name, path, data = nil, header = nil )

Sends an HTTP request to the HTTP server. This method also sends DATA string if DATA is given.

Returns a HTTPResponse object.

This method never raises Net::* exceptions.

       response = http.send_request('GET', '/index.html')
       puts response.body

[Source]

    # File net/http.rb, line 802
        def send_request( name, path, data = nil, header = nil )
          r = HTTPGenericRequest.new(name,(data ? true : false),true,path,header)
          request r, data
        end

request( req, body = nil ) {|+response+| ...}

Sends an HTTPRequest object REQUEST to the HTTP server. This method also sends DATA string if REQUEST is a post/put request. Giving DATA for get/head request causes ArgumentError.

When called with a block, yields an HTTPResponse object. The body of this response will not have been read yet; the caller can process it using HTTPResponse#read_body, if desired.

Returns a HTTPResponse object.

This method never raises Net::* exceptions.

[Source]

    # File net/http.rb, line 819
        def request( req, body = nil, &block )  # :yield: +response+

          unless started?
            start {
              req['connection'] = 'close'
              return request(req, body, &block)
            }
          end
          if proxy_user()
            req.proxy_basic_auth proxy_user(), proxy_pass()
          end

          begin_transport req
              req.exec @socket, @curr_http_version, edit_path(req.path), body
              begin
                res = HTTPResponse.read_new(@socket)
              end while HTTPContinue === res
              res.reading_body(@socket, req.response_body_permitted?) {
                yield res if block_given?
              }
          end_transport req, res

          res
        end

[Validate]