1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
/* Copyright (c) 2001 Matej Pfajfar.
* Copyright (c) 2001-2004, Roger Dingledine.
* Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
* Copyright (c) 2007-2019, The Tor Project, Inc. */
/* See LICENSE for licensing information */
/**
* \file tor_api.h
* \brief Public C API for the Tor network service.
*
* This interface is intended for use by programs that need to link Tor as
* a library, and launch it in a separate thread. If you have the ability
* to run Tor as a separate executable, you should probably do that instead
* of embedding it as a library.
*
* To use this API, first construct a tor_main_configuration_t object using
* tor_main_configuration_new(). Then, you use one or more other function
* calls (such as tor_main_configuration_set_command_line() to configure how
* Tor should be run. Finally, you pass the configuration object to
* tor_run_main().
*
* At this point, tor_run_main() will block its thread to run a Tor daemon;
* when the Tor daemon exits, it will return. See notes on bugs and
* limitations below.
*
* There is no other public C API to Tor: calling any C Tor function not
* documented in this file is not guaranteed to be stable.
**/
#ifndef TOR_API_H
#define TOR_API_H
typedef struct tor_main_configuration_t tor_main_configuration_t;
/**
* Create and return a new tor_main_configuration().
*/
tor_main_configuration_t *tor_main_configuration_new(void);
/**
* Set the command-line arguments in <b>cfg</b>.
*
* The <b>argc</b> and <b>argv</b> values here are as for main(). The
* contents of the argv pointer must remain unchanged until tor_run_main() has
* finished and you call tor_main_configuration_free().
*
* Return 0 on success, -1 on failure.
*/
int tor_main_configuration_set_command_line(tor_main_configuration_t *cfg,
int argc, char *argv[]);
#ifdef _WIN32
typedef SOCKET tor_control_socket_t;
#define INVALID_TOR_CONTROL_SOCKET INVALID_SOCKET
#else
typedef int tor_control_socket_t;
#define INVALID_TOR_CONTROL_SOCKET (-1)
#endif
/** DOCDOC */
tor_control_socket_t tor_main_configuration_setup_control_socket(
tor_main_configuration_t *cfg);
/**
* Release all storage held in <b>cfg</b>.
*
* Once you have passed a tor_main_configuration_t to tor_run_main(), you
* must not free it until tor_run_main() has finished.
*/
void tor_main_configuration_free(tor_main_configuration_t *cfg);
/**
* Return the name and version of the software implementing the tor_api
* functionality. Current implementors are "tor" and "libtorrunner".
*
* Note that if you're using libtorrunner, you'll see the version of
* libtorrunner, not the version of Tor that it's invoking for you.
*
* Added in Tor 0.3.5.1-alpha.
*
* Example return values include "tor 0.3.5.1-alpha" when linked directly
* against tor, and "libtorrunner 0.3.5.1-alpha" when linked against
* libtorrunner while it is invoking an arbitrary version of Tor. HOWEVER,
* the user MUST NOT depend on any particular format or contents of this
* string: there may be other things that implement Tor in the future.
**/
const char *tor_api_get_provider_version(void);
/**
* Run the tor process, as if from the command line.
*
* The command line arguments from tor_main_configuration_set_command_line()
* are taken as if they had been passed to main().
*
* This function will not return until Tor is done running. It returns zero
* on success, and nonzero on failure.
*
* If you want to control when Tor exits, make sure to configure a control
* socket. The OwningControllerFD option may be helpful there.
*
* BUG 23847: Sometimes, if you call tor_main a second time (after it has
* returned), Tor may crash or behave strangely. We have fixed all issues of
* this type that we could find, but more may remain.
*
* LIMITATION: You cannot run more than one instance of Tor in the same
* process at the same time. Concurrent calls will cause undefined behavior.
* We do not currently have plans to change this.
*
* LIMITATION: While we will try to fix any problems found here, you
* should be aware that Tor was originally written to run as its own
* process, and that the functionality of this file was added later. If
* you find any bugs or strange behavior, please report them, and we'll
* try to straighten them out.
*/
int tor_run_main(const tor_main_configuration_t *);
/**
* Run the tor process, as if from the command line.
*
* @deprecated Using this function from outside Tor is deprecated; you should
* use tor_run_main() instead.
*
* BUGS: This function has all the same bugs as tor_run_main().
*
* LIMITATIONS: This function has all the limitations of tor_run_main().
*/
int tor_main(int argc, char **argv);
#endif /* !defined(TOR_API_H) */
|
