include/git2/signature.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_signature_h__
0008 #define INCLUDE_git_signature_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012
0013 /**
0014  * @file git2/signature.h
0015  * @brief Git signature creation
0016  * @defgroup git_signature Git signature creation
0017  * @ingroup Git
0018  * @{
0019  */
0020 GIT_BEGIN_DECL
0021
0022 /**
0023  * Create a new action signature.
0024  *
0025  * Call `git_signature_free()` to free the data.
0026  *
0027  * Note: angle brackets ('<' and '>') characters are not allowed
0028  * to be used in either the `name` or the `email` parameter.
0029  *
0030  * @param out new signature, in case of error NULL
0031  * @param name name of the person
0032  * @param email email of the person
0033  * @param time time (in seconds from epoch) when the action happened
0034  * @param offset timezone offset (in minutes) for the time
0035  * @return 0 or an error code
0036  */
0037 GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset);
0038
0039 /**
0040  * Create a new action signature with a timestamp of 'now'.
0041  *
0042  * Call `git_signature_free()` to free the data.
0043  *
0044  * @param out new signature, in case of error NULL
0045  * @param name name of the person
0046  * @param email email of the person
0047  * @return 0 or an error code
0048  */
0049 GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email);
0050
0051 /**
0052  * Create a new action signature with default user and now timestamp.
0053  *
0054  * This looks up the user.name and user.email from the configuration and
0055  * uses the current time as the timestamp, and creates a new signature
0056  * based on that information.  It will return GIT_ENOTFOUND if either the
0057  * user.name or user.email are not set.
0058  *
0059  * @param out new signature
0060  * @param repo repository pointer
0061  * @return 0 on success, GIT_ENOTFOUND if config is missing, or error code
0062  */
0063 GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo);
0064
0065 /**
0066  * Create a new signature by parsing the given buffer, which is
0067  * expected to be in the format "Real Name <email> timestamp tzoffset",
0068  * where `timestamp` is the number of seconds since the Unix epoch and
0069  * `tzoffset` is the timezone offset in `hhmm` format (note the lack
0070  * of a colon separator).
0071  *
0072  * @param out new signature
0073  * @param buf signature string
0074  * @return 0 on success, GIT_EINVALID if the signature is not parseable, or an error code
0075  */
0076 GIT_EXTERN(int) git_signature_from_buffer(git_signature **out, const char *buf);
0077
0078 /**
0079  * Create a copy of an existing signature.  All internal strings are also
0080  * duplicated.
0081  *
0082  * Call `git_signature_free()` to free the data.
0083  *
0084  * @param dest pointer where to store the copy
0085  * @param sig signature to duplicate
0086  * @return 0 or an error code
0087  */
0088 GIT_EXTERN(int) git_signature_dup(git_signature **dest, const git_signature *sig);
0089
0090 /**
0091  * Free an existing signature.
0092  *
0093  * Because the signature is not an opaque structure, it is legal to free it
0094  * manually, but be sure to free the "name" and "email" strings in addition
0095  * to the structure itself.
0096  *
0097  * @param sig signature to free
0098  */
0099 GIT_EXTERN(void) git_signature_free(git_signature *sig);
0100
0101 /** @} */
0102 GIT_END_DECL
0103 #endif