src/git2/blob.h

   1 /*
   2  * This file is free software; you can redistribute it and/or modify
   3  * it under the terms of the GNU General Public License, version 2,
   4  * as published by the Free Software Foundation.
   5  *
   6  * In addition to the permissions in the GNU General Public License,
   7  * the authors give you unlimited permission to link the compiled
   8  * version of this file into combinations with other programs,
   9  * and to distribute those combinations without any restriction
  10  * coming from the use of this file.  (The General Public License
  11  * restrictions do apply in other respects; for example, they cover
  12  * modification of the file, and distribution when not linked into
  13  * a combined executable.)
  14  *
  15  * This file is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; see the file COPYING.  If not, write to
  22  * the Free Software Foundation, 51 Franklin Street, Fifth Floor,
  23  * Boston, MA 02110-1301, USA.
  24  */
  25 #ifndef INCLUDE_git_blob_h__
  26 #define INCLUDE_git_blob_h__
  27
  28 #include "common.h"
  29 #include "types.h"
  30 #include "oid.h"
  31 #include "repository.h"
  32
  33 /**
  34  * @file git2/blob.h
  35  * @brief Git blob load and write routines
  36  * @defgroup git_blob Git blob load and write routines
  37  * @ingroup Git
  38  * @{
  39  */
  40 GIT_BEGIN_DECL
  41
  42 /**
  43  * Lookup a blob object from a repository.
  44  * The generated blob object is owned by the revision
  45  * repo and shall not be freed by the user.
  46  *
  47  * @param blob pointer to the looked up blob
  48  * @param repo the repo to use when locating the blob.
  49  * @param id identity of the blob to locate.
  50  * @return 0 on success; error code otherwise
  51  */
  52 GIT_INLINE(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id)
  53 {
  54         return git_repository_lookup((git_object **)blob, repo, id, GIT_OBJ_BLOB);
  55 }
  56
  57 /**
  58  * Create a new in-memory git_blob.
  59  *
  60  * The blob object must be manually filled using
  61  * the 'set_rawcontent' methods before it can
  62  * be written back to disk.
  63  *
  64  * @param blob pointer to the new blob
  65  * @param repo The repository where the object will reside
  66  * @return 0 on success; error code otherwise
  67  */
  68 GIT_INLINE(int) git_blob_new(git_blob **blob, git_repository *repo)
  69 {
  70         return git_repository_newobject((git_object **)blob, repo, GIT_OBJ_BLOB);
  71 }
  72
  73 /**
  74  * Fill a blob with the contents inside
  75  * the pointed file.
  76  *
  77  * @param blob pointer to the new blob
  78  * @param filename name of the file to read
  79  * @return 0 on success; error code otherwise
  80  */
  81 GIT_EXTERN(int) git_blob_set_rawcontent_fromfile(git_blob *blob, const char *filename);
  82
  83 /**
  84  * Fill a blob with the contents inside
  85  * the pointed buffer
  86  *
  87  * @param blob pointer to the blob
  88  * @param buffer buffer with the contents for the blob
  89  * @param len size of the buffer
  90  * @return 0 on success; error code otherwise
  91  */
  92 GIT_EXTERN(int) git_blob_set_rawcontent(git_blob *blob, const void *buffer, size_t len);
  93
  94 /**
  95  * Get a read-only buffer with the raw content of a blob.
  96  *
  97  * A pointer to the raw content of a blob is returned;
  98  * this pointer is owned internally by the object and shall
  99  * not be free'd. The pointer may be invalidated at a later
 100  * time (e.g. when changing the contents of the blob).
 101  *
 102  * @param blob pointer to the blob
 103  * @return the pointer; NULL if the blob has no contents
 104  */
 105 GIT_EXTERN(const char *) git_blob_rawcontent(git_blob *blob);
 106
 107 /**
 108  * Get the size in bytes of the contents of a blob
 109  *
 110  * @param blob pointer to the blob
 111  * @return size on bytes
 112  */
 113 GIT_EXTERN(int) git_blob_rawsize(git_blob *blob);
 114
 115 /**
 116  * Read a file from the working folder of a repository
 117  * and write it to the Object Database as a loose blob,
 118  * if such doesn't exist yet.
 119  *
 120  * @param written_id return the id of the written blob
 121  * @param repo repository where the blob will be written
 122  * @param path file from which the blob will be created
 123  */
 124 GIT_EXTERN(int) git_blob_writefile(git_oid *written_id, git_repository *repo, const char *path);
 125
 126 /** @} */
 127 GIT_END_DECL
 128 #endif