Class: I2P::SAM::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/i2p/sam/client.rb

Overview

**I2P Simple Anonymous Messaging (SAM) V3 client.**

Examples:

Connecting to the I2P SAM bridge (1)

sam = I2P::SAM::Client.new(:port => 7656)

Connecting to the I2P SAM bridge (2)

I2P::SAM::Client.open(:port => 7656) do |sam|
  ...
end

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|client| ... } ⇒ Client

Initializes a new client instance.

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {})

Options Hash (options):

  • :host (String, #to_s) — default: DEFAULT_HOST
  • :port (Integer, #to_i) — default: DEFAULT_PORT
  • :version (Integer, #to_i) — default: PROTOCOL_VERSION

Yields:

  • (client)

Yield Parameters:



63
64
65
66
67
68
69
70
 
# File 'lib/i2p/sam/client.rb', line 63

def initialize(options = {}, &block)
  @options = options.dup
  @host    = (@options.delete(:host)    || DEFAULT_HOST).to_s
  @port    = (@options.delete(:port)    || DEFAULT_PORT).to_i
  @version = (@options.delete(:version) || PROTOCOL_VERSION).to_i

  block.call(self) if block_given?
end

Instance Attribute Details

#socket ⇒ TCPSocket (readonly)

Returns the socket connection to the SAM bridge.

Returns:

  • (TCPSocket) 


52
53
54
 
# File 'lib/i2p/sam/client.rb', line 52

def socket
  @socket
end

Class Method Details

.open(options = {}) {|client| ... } ⇒ void

This method returns an undefined value.

Establishes a connection to the SAM bridge.

Examples:

Connecting to the default port

sam = I2P::SAM::Client.open

Connecting to the given port

sam = I2P::SAM::Client.open(:port => 7656)

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {})

Options Hash (options):

  • :host (String, #to_s) — default: DEFAULT_HOST
  • :port (Integer, #to_i) — default: DEFAULT_PORT
  • :version (Integer, #to_i) — default: PROTOCOL_VERSION

Yields:

  • (client)

Yield Parameters:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/i2p/sam/client.rb', line 32

def self.open(options = {}, &block)
  client = self.new(options)
  client.connect.hello # handshake

  unless block_given?
    client
  else
    begin
      result = block.call(client)
    ensure
      client.disconnect
    end
    result
  end
end

Instance Method Details

#connect ⇒ void Also known as: reconnect

This method returns an undefined value.

Establishes a connection to the SAM bridge.

If called after the connection has already been established, disconnects and then reconnects to the bridge.

Examples:

sam.connect


96
97
98
99
100
101
 
# File 'lib/i2p/sam/client.rb', line 96

def connect
  disconnect if connected?
  @socket = TCPSocket.new(@host, @port)
  @socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
  self
end

#connected? ⇒ Boolean

Returns ‘true` if a connection to the SAM bridge has been established and is active.

Examples:

sam.connected?             #=> true
sam.disconnect
sam.connected?             #=> false

Returns:

  • (Boolean) 


82
83
84
 
# File 'lib/i2p/sam/client.rb', line 82

def connected?
  !!@socket
end

#disconnect ⇒ void Also known as: close

This method returns an undefined value.

Closes the connection to the SAM bridge.

If called after the connection has already been closed, does nothing.

Examples:

sam.disconnect


113
114
115
116
117
 
# File 'lib/i2p/sam/client.rb', line 113

def disconnect
  @socket.close if @socket && !@socket.closed?
  @socket = nil
  self
end

#generate_dest ⇒ KeyPair Also known as: generate_destination

Generates a new I2P destination and returns the key pair for it.

Examples:

key_pair = sam.generate_dest

Returns:



164
165
166
167
 
# File 'lib/i2p/sam/client.rb', line 164

def generate_dest
  send_msg(:dest, :generate)
  KeyPair.parse(read_reply[:priv])
end

#hello(options = {}) ⇒ Float

Performs the SAM protocol handshake and returns the autonegotiated protocol version.

Examples:

sam.hello                            #=> 3.0
sam.hello(:min => 3.0, :max => 4.0)  #=> 3.0

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {})

Options Hash (options):

  • :min (Float, #to_f) — default: PROTOCOL_VERSION
  • :max (Float, #to_f) — default: PROTOCOL_VERSION

Returns:

  • (Float)

Raises:

  • (ProtocolNotSupported) —

    if the handshake failed



135
136
137
138
139
140
141
 
# File 'lib/i2p/sam/client.rb', line 135

def hello(options = {})
  send_msg(:hello, :version, {
    :min => '%.1f' % (options[:min] || @version).to_f,
    :max => '%.1f' % (options[:max] || @version).to_f,
  })
  read_reply[:version].to_f
end

#lookup_name(name) ⇒ Destination

Returns the I2P destination corresponding to ‘name`.

Examples:

sam.lookup_name("forum.i2p")         #=> #<I2P::Destination:...>

Parameters:

  • name (String, #to_s)

Returns:

Raises:



152
153
154
155
 
# File 'lib/i2p/sam/client.rb', line 152

def lookup_name(name)
  send_msg(:naming, :lookup, :name => name.to_s)
  Destination.parse(read_reply[:value])
end