I2P SAM session. More...

#include <i2p.h>

Collaboration diagram for i2p::sam::Session:

Classes
struct	Reply
	A reply from the SAM proxy. More...

Public Member Functions
	Session (const fs::path &private_key_file, const Proxy &control_host, CThreadInterrupt *interrupt)
	Construct a session. More...

	Session (const Proxy &control_host, CThreadInterrupt *interrupt)
	Construct a transient session which will generate its own I2P private key rather than read the one from disk (it will not be saved on disk either and will be lost once this object is destroyed). More...

	~Session ()
	Destroy the session, closing the internally used sockets. More...

bool	Listen (Connection &conn) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Start listening for an incoming connection. More...

bool	Accept (Connection &conn) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Wait for and accept a new incoming connection. More...

bool	Connect (const CService &to, Connection &conn, bool &proxy_error) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Connect to an I2P peer. More...

Private Member Functions
Reply	SendRequestAndGetReply (const Sock &sock, const std::string &request, bool check_result_ok=true) const
	Send request and get a reply from the SAM proxy. More...

std::unique_ptr< Sock >	Hello () const EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Open a new connection to the SAM proxy. More...

void	CheckControlSock () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Check the control socket for errors and possibly disconnect. More...

void	DestGenerate (const Sock &sock) EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Generate a new destination with the SAM proxy and set `m_private_key` to it. More...

void	GenerateAndSavePrivateKey (const Sock &sock) EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Generate a new destination with the SAM proxy, set `m_private_key` to it and save it on disk to `m_private_key_file`. More...

Binary	MyDestination () const EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Derive own destination from `m_private_key`. More...

void	CreateIfNotCreatedAlready () EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Create the session if not already created. More...

std::unique_ptr< Sock >	StreamAccept () EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Open a new connection to the SAM proxy and issue "STREAM ACCEPT" request using the existing session id. More...

void	Disconnect () EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Destroy the session, closing the internally used sockets. More...

Binary m_private_key	GUARDED_BY (m_mutex)
	The private key of this peer. More...

std::unique_ptr< Sock > m_control_sock	GUARDED_BY (m_mutex)
	SAM control socket. More...

CService m_my_addr	GUARDED_BY (m_mutex)
	Our .b32.i2p address. More...

std::string m_session_id	GUARDED_BY (m_mutex)
	SAM session id. More...

Private Attributes
const fs::path	m_private_key_file
	The name of the file where this peer's private key is stored (in binary). More...

const Proxy	m_control_host
	The SAM control service proxy. More...

CThreadInterrupt *const	m_interrupt
	Cease network activity when this is signaled. More...

Mutex	m_mutex
	Mutex protecting the members that can be concurrently accessed. More...

const bool	m_transient
	Whether this is a transient session (the I2P private key will not be read or written to disk). More...

Detailed Description

I2P SAM session.

Definition at line 56 of file i2p.h.

Constructor & Destructor Documentation

◆ Session() [1/2]

i2p::sam::Session::Session	(	const fs::path &	private_key_file,
		const Proxy &	control_host,
		CThreadInterrupt *	interrupt
	)

Construct a session.

This will not initiate any IO, the session will be lazily created later when first used.

Parameters

[in]	private_key_file	Path to a private key file. If the file does not exist then the private key will be generated and saved into the file.
[in]	control_host	Location of the SAM proxy.
[in,out]	interrupt	If this is signaled then all operations are canceled as soon as possible and executing methods throw an exception. Notice: only a pointer to the `CThreadInterrupt` object is saved, so it must not be destroyed earlier than this `Session` object.

Definition at line 119 of file i2p.cpp.

◆ Session() [2/2]

i2p::sam::Session::Session	(	const Proxy &	control_host,
		CThreadInterrupt *	interrupt
	)

Construct a transient session which will generate its own I2P private key rather than read the one from disk (it will not be saved on disk either and will be lost once this object is destroyed).

This will not initiate any IO, the session will be lazily created later when first used.

Parameters

[in]	control_host	Location of the SAM proxy.
[in,out]	interrupt	If this is signaled then all operations are canceled as soon as possible and executing methods throw an exception. Notice: only a pointer to the `CThreadInterrupt` object is saved, so it must not be destroyed earlier than this `Session` object.

Definition at line 129 of file i2p.cpp.

◆ ~Session()

i2p::sam::Session::~Session ( )

Destroy the session, closing the internally used sockets.

The sockets that have been returned by Accept() or Connect() will not be closed, but they will be closed by the SAM proxy because the session is destroyed. So they will return an error next time we try to read or write to them.

Definition at line 136 of file i2p.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ Accept()

bool i2p::sam::Session::Accept ( Connection & conn )

Wait for and accept a new incoming connection.

Parameters

[in,out] conn The sock member is used for waiting and accepting. Upon successful completion the peer member will be set to the address of the incoming peer.

Returns: true on success

Definition at line 157 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CheckControlSock()

void i2p::sam::Session::CheckControlSock ( )

private

Check the control socket for errors and possibly disconnect.

Definition at line 341 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Connect()

bool i2p::sam::Session::Connect	(	const CService &	to,
		Connection &	conn,
		bool &	proxy_error
	)

Connect to an I2P peer.

Parameters

[in]	to	Peer to connect to.
[out]	conn	Established connection. Only set if `true` is returned.
[out]	proxy_error	If an error occurs due to proxy or general network failure, then this is set to `true`. If an error occurs due to unreachable peer (likely peer is down), then it is set to `false`. Only set if `false` is returned.

Returns: true on success

Definition at line 221 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CreateIfNotCreatedAlready()

void i2p::sam::Session::CreateIfNotCreatedAlready ( )

private

Create the session if not already created.

Reads the private key file and connects to the SAM proxy.

Exceptions

std::runtime_error if an error occurs

Definition at line 407 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DestGenerate()

void i2p::sam::Session::DestGenerate ( const Sock & sock )

private

Generate a new destination with the SAM proxy and set m_private_key to it.

Parameters

[in] sock Socket to use for talking to the SAM proxy.

Exceptions

std::runtime_error if an error occurs

Definition at line 352 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Disconnect()

void i2p::sam::Session::Disconnect ( )

private

Destroy the session, closing the internally used sockets.

Definition at line 481 of file i2p.cpp.

Here is the caller graph for this function:

◆ GenerateAndSavePrivateKey()

void i2p::sam::Session::GenerateAndSavePrivateKey ( const Sock & sock )

private

Generate a new destination with the SAM proxy, set m_private_key to it and save it on disk to m_private_key_file.

Parameters

[in] sock Socket to use for talking to the SAM proxy.

Exceptions

std::runtime_error if an error occurs

Definition at line 363 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GUARDED_BY() [1/4]

Binary m_private_key i2p::sam::Session::GUARDED_BY ( m_mutex )

private

The private key of this peer.

See also: The reply to the "DEST GENERATE" command in https://geti2p.net/en/docs/api/samv3

◆ GUARDED_BY() [2/4]

std::unique_ptr< Sock > m_control_sock i2p::sam::Session::GUARDED_BY ( m_mutex )

private

SAM control socket.

Used to connect to the I2P SAM service and create a session ("SESSION CREATE"). With the established session id we later open other connections to the SAM service to accept incoming I2P connections and make outgoing ones. If not connected then this unique_ptr will be empty. See https://geti2p.net/en/docs/api/samv3

◆ GUARDED_BY() [3/4]

CService m_my_addr i2p::sam::Session::GUARDED_BY ( m_mutex )

private

Our .b32.i2p address.

Derived from m_private_key.

◆ GUARDED_BY() [4/4]

std::string m_session_id i2p::sam::Session::GUARDED_BY ( m_mutex )

private

SAM session id.

◆ Hello()

std::unique_ptr< Sock > i2p::sam::Session::Hello ( ) const

private

Open a new connection to the SAM proxy.

Returns: a connected socket

Exceptions

std::runtime_error if an error occurs

Definition at line 328 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Listen()

bool i2p::sam::Session::Listen ( Connection & conn )

Start listening for an incoming connection.

Parameters

[out] conn Upon successful completion the sock and me members will be set to the listening socket and address.

Returns: true on success

Definition at line 142 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ MyDestination()

Binary i2p::sam::Session::MyDestination ( ) const

private

Derive own destination from m_private_key.

See also: https://geti2p.net/spec/common-structures#destination

Returns: an I2P destination

Definition at line 375 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SendRequestAndGetReply()

Session::Reply i2p::sam::Session::SendRequestAndGetReply	(	const Sock &	sock,
		const std::string &	request,
		bool	check_result_ok = `true`
	)		const

private

Send request and get a reply from the SAM proxy.

Parameters

[in]	sock	A socket that is connected to the SAM proxy.
[in]	request	Raw request to send, a newline terminator is appended to it.
[in]	check_result_ok	If true then after receiving the reply a check is made whether it contains "RESULT=OK" and an exception is thrown if it does not.

Exceptions

std::runtime_error if an error occurs

Definition at line 292 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ StreamAccept()

std::unique_ptr< Sock > i2p::sam::Session::StreamAccept ( )

private

Open a new connection to the SAM proxy and issue "STREAM ACCEPT" request using the existing session id.

Returns: the idle socket that is waiting for a peer to connect to us

Exceptions

std::runtime_error if an error occurs

Definition at line 460 of file i2p.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ m_control_host

const Proxy i2p::sam::Session::m_control_host

private

The SAM control service proxy.

Definition at line 233 of file i2p.h.

◆ m_interrupt

CThreadInterrupt* const i2p::sam::Session::m_interrupt

private

Cease network activity when this is signaled.

Definition at line 238 of file i2p.h.

◆ m_mutex

Mutex i2p::sam::Session::m_mutex

mutableprivate

Mutex protecting the members that can be concurrently accessed.

Definition at line 243 of file i2p.h.

◆ m_private_key_file

const fs::path i2p::sam::Session::m_private_key_file

private

The name of the file where this peer's private key is stored (in binary).

Definition at line 228 of file i2p.h.

◆ m_transient

const bool i2p::sam::Session::m_transient

private

Whether this is a transient session (the I2P private key will not be read or written to disk).

Definition at line 277 of file i2p.h.

The documentation for this class was generated from the following files:

src/i2p.h
src/i2p.cpp

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Session() [1/2]

◆ Session() [2/2]

◆ ~Session()

Member Function Documentation

◆ Accept()

◆ CheckControlSock()

◆ Connect()

◆ CreateIfNotCreatedAlready()

◆ DestGenerate()

◆ Disconnect()

◆ GenerateAndSavePrivateKey()

◆ GUARDED_BY() [1/4]

◆ GUARDED_BY() [2/4]

◆ GUARDED_BY() [3/4]

◆ GUARDED_BY() [4/4]

◆ Hello()

◆ Listen()

◆ MyDestination()

◆ SendRequestAndGetReply()

◆ StreamAccept()

Member Data Documentation

◆ m_control_host

◆ m_interrupt

◆ m_mutex

◆ m_private_key_file

◆ m_transient