1/* External declarations for the libdebuginfod client library.
2   Copyright (C) 2019-2020 Red Hat, Inc.
3   This file is part of elfutils.
4
5   This file is free software; you can redistribute it and/or modify
6   it under the terms of either
7
8   * the GNU Lesser General Public License as published by the Free
9       Software Foundation; either version 3 of the License, or (at
10       your option) any later version
11
12   or
13
14   * the GNU General Public License as published by the Free
15       Software Foundation; either version 2 of the License, or (at
16       your option) any later version
17
18   or both in parallel, as here.
19
20   elfutils is distributed in the hope that it will be useful, but
21   WITHOUT ANY WARRANTY; without even the implied warranty of
22   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
23   General Public License for more details.
24
25   You should have received copies of the GNU General Public License and
26   the GNU Lesser General Public License along with this program.  If
27   not, see <http://www.gnu.org/licenses/>.  */
28
29#ifndef _DEBUGINFOD_CLIENT_H
30#define _DEBUGINFOD_CLIENT_H 1
31
32/* Names of environment variables that control the client logic. */
33#define DEBUGINFOD_URLS_ENV_VAR "DEBUGINFOD_URLS"
34#define DEBUGINFOD_CACHE_PATH_ENV_VAR "DEBUGINFOD_CACHE_PATH"
35#define DEBUGINFOD_TIMEOUT_ENV_VAR "DEBUGINFOD_TIMEOUT"
36#define DEBUGINFOD_PROGRESS_ENV_VAR "DEBUGINFOD_PROGRESS"
37#define DEBUGINFOD_VERBOSE_ENV_VAR "DEBUGINFOD_VERBOSE"
38
39/* The libdebuginfod soname.  */
40#define DEBUGINFOD_SONAME "@LIBDEBUGINFOD_SONAME@"
41
42/* Handle for debuginfod-client connection.  */
43typedef struct debuginfod_client debuginfod_client;
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49/* Create a handle for a new debuginfod-client session.  */
50debuginfod_client *debuginfod_begin (void);
51
52/* Query the urls contained in $DEBUGINFOD_URLS for a file with
53   the specified type and build id.  If build_id_len == 0, the
54   build_id is supplied as a lowercase hexadecimal string; otherwise
55   it is a binary blob of given length.
56
57   If successful, return a file descriptor to the target, otherwise
58   return a posix error code.  If successful, set *path to a
59   strdup'd copy of the name of the same file in the cache.
60   Caller must free() it later. */
61
62int debuginfod_find_debuginfo (debuginfod_client *client,
63			       const unsigned char *build_id,
64                               int build_id_len,
65                               char **path);
66
67int debuginfod_find_executable (debuginfod_client *client,
68				const unsigned char *build_id,
69                                int build_id_len,
70                                char **path);
71
72int debuginfod_find_source (debuginfod_client *client,
73			    const unsigned char *build_id,
74                            int build_id_len,
75                            const char *filename,
76                            char **path);
77
78typedef int (*debuginfod_progressfn_t)(debuginfod_client *c, long a, long b);
79void debuginfod_set_progressfn(debuginfod_client *c,
80			       debuginfod_progressfn_t fn);
81
82void debuginfod_set_verbose_fd(debuginfod_client *c, int fd);
83
84/* Set the user parameter.  */
85void debuginfod_set_user_data (debuginfod_client *client, void *value);
86
87/* Get the user parameter.  */
88void* debuginfod_get_user_data (debuginfod_client *client);
89
90/* Get the current or last active URL, if known.  */
91const char* debuginfod_get_url (debuginfod_client *client);
92
93/* Add an outgoing HTTP request  "Header: Value".  Copies string.  */
94int debuginfod_add_http_header (debuginfod_client *client, const char* header);
95
96/* Release debuginfod client connection context handle.  */
97void debuginfod_end (debuginfod_client *client);
98
99#ifdef __cplusplus
100}
101#endif
102
103
104#endif /* _DEBUGINFOD_CLIENT_H */
105