README.md 2.71 KB
Newer Older
Richard's avatar
Richard committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# **bobcpp** #

### A C++ I2P BOB client library

bobcpp is a C++ client library to communicate with the I2P BOB service.
It can be used to programatically manage tunnels to the I2P network.
After creating tunnels you can then connect to them on localhost with your application and communicate anonymously within the I2P network.

The BOB API documentation is available here: https://geti2p.net/en/docs/api/bob

At this moment there is only a Qt implementation (QTcpSocket) available, though by design it is easy to add another implementation (e.g. Boost ASIO, Winsock, etc.).

# Design

To keep the library as simple as possible it is implmented in a blocking fashion and throws exceptions when errors occur.
All methods will block and wait until the network actions are completed.
If you need to open/close tunnels without blocking then you can achieve this by using a worker thread.

# Quickstart Guide

The AbstractClient class provides the interface for the client.
Richard's avatar
Richard committed
22
It contains methods that correspond with the BOB commands, e.g. the method `client->inhost("127.0.0.1")` corresponds to the BOB command `inhost 127.0.0.1`.
Richard's avatar
Richard committed
23
24
25

Below is an example of how to open a single tunnel.

Richard's avatar
Richard committed
26
```cpp
Richard's avatar
Richard committed
27
#include <bobcpp/bobcpp.h>
Richard's avatar
Richard committed
28

Richard's avatar
Richard committed
29
30
31
32
33
34
35
int main(int argc, char *argv[]) {
    try {
        auto client = CreateClient(); // returns implementation specific shared pointer
        client->connect(); // open a socket to the default BOB host and port

        client->setnick("my-tunnel");
        auto pubkey = client->newkeys();
Richard's avatar
Richard committed
36
        client->inhost("127.0.0.1");
Richard's avatar
Richard committed
37
38
        client->inport("33555");
        client->start();
Richard's avatar
Richard committed
39
        
Richard's avatar
Richard committed
40
41
42
        // Now you can connect your own TCP socket to localhost:33555
        // and send the destination on the first line (e.g. "zzz.i2p\n" without quotes)to connect to it.
        // After that you are directly communicating with the destination.
Richard's avatar
Richard committed
43
44
45
        
        // once finished, stop the tunnels, optionally clear them (remove from BOB) and then quit and disconnect.
        client->stop();
Richard's avatar
Richard committed
46
        client->clear(); // removes the stopped tunnels
Richard's avatar
Richard committed
47
48
49
50
        client->quit();
        
        // close the socket
        client->disconnect();
Richard's avatar
Richard committed
51
52
53
54
55
56
57
    } catch(...) {
        // see bobcpp/Exception.h for the possible exceptions you can handle / possibly recover from
    }
    return 0;
}
```

Richard's avatar
Richard committed
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
# Building

This project uses CMake to help build the project.

**Dependencies**

* CMake >= v3.1.0
* Qt5 Core, Network (currently the only available implementation)

**Build Instructions (Unix)**

```bash
git clone https://gitlab.com/rszibele/bobcpp.git
mkdir bobcpp-build
cd bobcpp-build
cmake ../bobcpp/
make
make install
```
Richard's avatar
Richard committed
77
78
79

# License

Richard's avatar
Richard committed
80
This project is licensed under the BSD 3-clause license, which can be found in the file LICENSE in the root of the project source code.