a324d61101e9ea2afbcfd9fec5b5427b38bd1860
[moonshot-ui.git] / libmoonshot / libmoonshot.h
1 /* libmoonshot - Moonshot client library
2  * Copyright (c) 2011, JANET(UK)
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  *
12  * 2. Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * 3. Neither the name of JANET(UK) nor the names of its contributors
17  *    may be used to endorse or promote products derived from this software
18  *    without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30  * SUCH DAMAGE.
31  *
32  * Author: Sam Thursfield <samthursfield@codethink.co.uk>
33  */
34
35 #ifndef __LIBMOONSHOT_H
36 #define __LIBMOONSHOT_H
37
38 /**
39  * moonshot_free:
40  * @pointer: pointer to be freed
41  *
42  * All the strings returned by the get_identity() functions must be
43  * freed using this function when they are no longer needed.
44  *
45  * @pointer may be %NULL, in which case no action is taken.
46  */
47 void moonshot_free (void *data);
48
49 typedef enum {
50     MOONSHOT_ERROR_UNABLE_TO_START_SERVICE,
51     MOONSHOT_ERROR_NO_IDENTITY_SELECTED,
52     MOONSHOT_ERROR_INSTALLATION_ERROR,
53     MOONSHOT_ERROR_OS_ERROR,
54     MOONSHOT_ERROR_IPC_ERROR
55 } MoonshotErrorCode;
56
57 typedef struct {
58     int   code;    /* A MoonshotErrorCode */
59     char *message;
60 } MoonshotError;
61
62 /**
63  * moonshot_error_free:
64  * @error: A #MoonshotError
65  *
66  * Releases the memory used by @error. This function must be called if
67  * a function has returned an error, once it has been reported.
68  */
69 void moonshot_error_free (MoonshotError *error);
70
71 /**
72  * moonshot_get_identity:
73  * @nai: Name and issuer constraint for the required identity, or %NULL.
74  * @password: Password for the identity, or %NULL.
75  * @service: Service constraint for the required identity, or %NULL.
76  * @nai_out: A pointer to a string which receives the name and issuer of the
77  *           selected identity.
78  * @password_out: A pointer to a string which receives the password.
79  * @server_certificate_hash_out: Receives a hash of the identity server's
80  *                               certificate, or %NULL.
81  * @ca_certificate_out: The CA certificate, if @server_certificate_hash was
82  *                      %NULL.
83  * @subject_name_constraint_out: Set if @ca_certificate is set, otherwise %NULL.
84  * @subject_alt_name_constraint_out: Set if @ca_certificate is set, otherwise
85  *                                   %NULL.
86  * @error: Return location for a #MoonshotError.
87  *
88  * This function calls the Moonshot server to request an ID card. The server
89  * will be activated if it is not already running. The user interface will be
90  * displayed if there is more than one matching identity and the user will be
91  * asked to select one.
92  *
93  * There are two types of trust anchor that may be returned. If
94  * @server_certificate_hash is non-empty, the remaining parameters will be
95  * empty. Otherwise, the @ca_certificate parameter and the subject name
96  * constraints will be returned.
97  *
98  * Error reporting is handled by a simple mechanism similar to #GError. If
99  * an error occurs, as well as returning %FALSE a #MoonshotError object will
100  * be stored at *@error, with a code and message string. This must be freed
101  * using moonshot_error_free().
102  *
103  * Return value: %TRUE if an identity was successfully selected, %FALSE on
104  *               failure.
105  */
106 int moonshot_get_identity (const char     *nai,
107                            const char     *password,
108                            const char     *service,
109                            char          **nai_out,
110                            char          **password_out,
111                            char          **server_certificate_hash_out,
112                            char          **ca_certificate_out,
113                            char          **subject_name_constraint_out,
114                            char          **subject_alt_name_constraint_out,
115                            MoonshotError **error);
116
117 /**
118  * moonshot_get_default_identity:
119  * @nai_out: A pointer to a string which receives the name and issuer of the
120  *           identity.
121  * @password_out: A pointer to a string which receives the password.
122  * @server_certificate_hash_out: Receives a hash of the identity server's
123  *                               certificate, or %NULL.
124  * @ca_certificate_out: The CA certificate, if @server_certificate_hash was
125  *                      %NULL.
126  * @subject_name_constraint_out: Set if @ca_certificate is set, otherwise %NULL.
127  * @subject_alt_name_constraint_out: Set if @ca_certificate is set, otherwise
128  *                                   %NULL.
129  * @error: Return location for a #MoonshotError.
130  *
131  * This function calls the Moonshot server to request the default identity
132  * (the one most recently used). Its semantics are otherwise the same as
133  * moonshot_get_identity().
134  *
135  * Return value: %TRUE if an identity was available, otherwise %FALSE.
136  */
137 int moonshot_default_get_identity (char          **nai_out,
138                                    char          **password_out,
139                                    char          **server_certificate_hash_out,
140                                    char          **ca_certificate_out,
141                                    char          **subject_name_constraint_out,
142                                    char          **subject_alt_name_constraint_out,
143                                    MoonshotError **error);
144
145 #endif