aboutsummaryrefslogtreecommitdiff
path: root/plugin-api.h
blob: 109f729c928f9819999bb8dd53803ca5ee923efc (plain)
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
/*
 * plugin-api.h: plugin API for ponymap
 *
 * Copyright (c) 2014, Přemysl Janouch <p.janouch@gmail.com>
 * All rights reserved.
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 */

#ifndef PLUGIN_API_H
#define PLUGIN_API_H

// This API is meant to be as simplistic as is realistically possible.

/// The version of the API, and by extension, of all the following structs
#define API_VERSION 1

///< Opaque object with data relating to a service scan
struct unit;

enum
{
	SERVICE_SUPPORTS_TLS = (1 << 0)     ///< Plain TLS can be used
};

struct service
{
	const char *name;                   ///< Name of the service
	int flags;                          ///< Service flags
	void *user_data;                    ///< User data

	// scan_init -> on_data* -> [on_eof/on_error] -> on_aborted -> scan_free

	/// Initialize a scan, returning a handle to it
	void *(*scan_init) (struct service *self, struct unit *u);

	/// Destroy the handle created for the scan
	void (*scan_free) (void *handle);

	/// We have received some data from the peer
	void (*on_data) (void *handle, const void *data, size_t len);

	/// Server has closed the connection
	void (*on_eof) (void *handle);

	// XXX: do we need these at all?  Is there any use for them?

	/// Network or other error has occured
	void (*on_error) (void *handle);

	/// The scan has been aborted
	void (*on_aborted) (void *handle);
};

struct plugin_api
{
	/// Register the plugin for a service
	void (*register_service) (void *ctx, struct service *info);

	/// Retrieve an item from the configuration
	const char *(*get_config) (void *ctx, const char *key);

	/// Get the IP address of the target as a string
	const char *(*unit_get_address) (struct unit *u);

	/// Send some data to the peer
	ssize_t (*unit_write) (struct unit *u, const void *buf, size_t len);

	/// Mark the scan as un/successful
	void (*unit_set_success) (struct unit *u, bool success);

	/// Add some information resulting from the scan
	void (*unit_add_info) (struct unit *u, const char *result);

	/// Abort the scan, close the connection
	void (*unit_abort) (struct unit *u);
};

struct plugin_info
{
	/// Version of the API used by this plugin
	int32_t api_version;

	/// Let the plugin initialize itself and register any services.
	/// The context needs to be passed to the relevant API functions.
	bool (*initialize) (void *ctx, struct plugin_api *api);
};

#endif  // ! PLUGIN_API_H