libgit2.signature source code

1 /*
2  * Copyright (C) the libgit2 contributors. All rights reserved.
3  *
4  * This file is part of libgit2, distributed under the GNU GPL v2 with
5  * a Linking Exception. For full terms see the included COPYING file.
6  */
7 /**
8  * License: GPL-2.0(Linking Exception)
9  */
10 module libgit2.signature;
11 
12 
13 private static import libgit2.types;
14 private import libgit2.common: GIT_EXTERN;
15 
16 /*
17  * @file git2/signature.h
18  * @brief Git signature creation
19  * @defgroup libgit2.types.git_signature Git signature creation
20  * @ingroup Git
21  * @{
22  */
23 extern (C):
24 nothrow @nogc:
25 public:
26 
27 /**
28  * Create a new action signature.
29  *
30  * Call `git_signature_free()` to free the data.
31  *
32  * Note: angle brackets ('<' and '>') characters are not allowed
33  * to be used in either the `name` or the `email` parameter.
34  *
35  * Params:
36  *      out_ = new signature, in case of error null
37  *      name = name of the person
38  *      email = email of the person
39  *      time = time (in seconds from epoch) when the action happened
40  *      offset = timezone offset (in minutes) for the time
41  *
42  * Returns: 0 or an error code
43  */
44 @GIT_EXTERN
45 int git_signature_new(libgit2.types.git_signature** out_, const (char)* name, const (char)* email, libgit2.types.git_time_t time, int offset);
46 
47 /**
48  * Create a new action signature with a timestamp of 'now'.
49  *
50  * Call `git_signature_free()` to free the data.
51  *
52  * Params:
53  *      out_ = new signature, in case of error null
54  *      name = name of the person
55  *      email = email of the person
56  *
57  * Returns: 0 or an error code
58  */
59 @GIT_EXTERN
60 int git_signature_now(libgit2.types.git_signature** out_, const (char)* name, const (char)* email);
61 
62 /**
63  * Create a new action signature with default user and now timestamp.
64  *
65  * This looks up the user.name and user.email from the configuration and
66  * uses the current time as the timestamp, and creates a new signature
67  * based on that information.  It will return git_error_code.GIT_ENOTFOUND if either the
68  * user.name or user.email are not set.
69  *
70  * Params:
71  *      out_ = new signature
72  *      repo = repository pointer
73  *
74  * Returns: 0 on success, git_error_code.GIT_ENOTFOUND if config is missing, or error code
75  */
76 @GIT_EXTERN
77 int git_signature_default(libgit2.types.git_signature** out_, libgit2.types.git_repository* repo);
78 
79 /**
80  * Create a new signature by parsing the given buffer, which is
81  * expected to be in the format "Real Name <email> timestamp tzoffset",
82  * where `timestamp` is the number of seconds since the Unix epoch and
83  * `tzoffset` is the timezone offset in `hhmm` format (note the lack
84  * of a colon separator).
85  *
86  * Params:
87  *      out_ = new signature
88  *      buf = signature string
89  *
90  * Returns: 0 on success, git_error_code.GIT_EINVALID if the signature is not parseable, or an error code
91  */
92 @GIT_EXTERN
93 int git_signature_from_buffer(libgit2.types.git_signature** out_, const (char)* buf);
94 
95 /**
96  * Create a copy of an existing signature.  All internal strings are also
97  * duplicated.
98  *
99  * Call `git_signature_free()` to free the data.
100  *
101  * Params:
102  *      dest = pointer where to store the copy
103  *      sig = signature to duplicate
104  *
105  * Returns: 0 or an error code
106  */
107 @GIT_EXTERN
108 int git_signature_dup(libgit2.types.git_signature** dest, const (libgit2.types.git_signature)* sig);
109 
110 /**
111  * Free an existing signature.
112  *
113  * Because the signature is not an opaque structure, it is legal to free it
114  * manually, but be sure to free the "name" and "email" strings in addition
115  * to the structure itself.
116  *
117  * Params:
118  *      sig = signature to free
119  */
120 @GIT_EXTERN
121 void git_signature_free(libgit2.types.git_signature* sig);
122 
123 /* @} */