include/git2/blob.h

   1 /*
   2  * Copyright (C) 2009-2011 the libgit2 contributors
   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 #ifndef INCLUDE_git_blob_h__
   8 #define INCLUDE_git_blob_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13 #include "object.h"
  14
  15 /**
  16  * @file git2/blob.h
  17  * @brief Git blob load and write routines
  18  * @defgroup git_blob Git blob load and write routines
  19  * @ingroup Git
  20  * @{
  21  */
  22 GIT_BEGIN_DECL
  23
  24 /**
  25  * Lookup a blob object from a repository.
  26  *
  27  * @param blob pointer to the looked up blob
  28  * @param repo the repo to use when locating the blob.
  29  * @param id identity of the blob to locate.
  30  * @return GIT_SUCCESS or an error code
  31  */
  32 GIT_INLINE(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id)
  33 {
  34         return git_object_lookup((git_object **)blob, repo, id, GIT_OBJ_BLOB);
  35 }
  36
  37 /**
  38  * Lookup a blob object from a repository,
  39  * given a prefix of its identifier (short id).
  40  *
  41  * @see git_object_lookup_prefix
  42  *
  43  * @param blob pointer to the looked up blob
  44  * @param repo the repo to use when locating the blob.
  45  * @param id identity of the blob to locate.
  46  * @param len the length of the short identifier
  47  * @return GIT_SUCCESS or an error code
  48  */
  49 GIT_INLINE(int) git_blob_lookup_prefix(git_blob **blob, git_repository *repo, const git_oid *id, unsigned int len)
  50 {
  51         return git_object_lookup_prefix((git_object **)blob, repo, id, len, GIT_OBJ_BLOB);
  52 }
  53
  54 /**
  55  * Close an open blob
  56  *
  57  * This is a wrapper around git_object_free()
  58  *
  59  * IMPORTANT:
  60  * It *is* necessary to call this method when you stop
  61  * using a blob. Failure to do so will cause a memory leak.
  62  *
  63  * @param blob the blob to close
  64  */
  65
  66 GIT_INLINE(void) git_blob_free(git_blob *blob)
  67 {
  68         git_object_free((git_object *) blob);
  69 }
  70
  71
  72 /**
  73  * Get a read-only buffer with the raw content of a blob.
  74  *
  75  * A pointer to the raw content of a blob is returned;
  76  * this pointer is owned internally by the object and shall
  77  * not be free'd. The pointer may be invalidated at a later
  78  * time.
  79  *
  80  * @param blob pointer to the blob
  81  * @return the pointer; NULL if the blob has no contents
  82  */
  83 GIT_EXTERN(const void *) git_blob_rawcontent(git_blob *blob);
  84
  85 /**
  86  * Get the size in bytes of the contents of a blob
  87  *
  88  * @param blob pointer to the blob
  89  * @return size on bytes
  90  */
  91 GIT_EXTERN(size_t) git_blob_rawsize(git_blob *blob);
  92
  93 /**
  94  * Read a file from the working folder of a repository
  95  * and write it to the Object Database as a loose blob
  96  *
  97  * @param oid return the id of the written blob
  98  * @param repo repository where the blob will be written.
  99  *      this repository cannot be bare
 100  * @param path file from which the blob will be created,
 101  *      relative to the repository's working dir
 102  * @return GIT_SUCCESS or an error code
 103  */
 104 GIT_EXTERN(int) git_blob_create_fromfile(git_oid *oid, git_repository *repo, const char *path);
 105
 106
 107 /**
 108  * Write an in-memory buffer to the ODB as a blob
 109  *
 110  * @param oid return the oid of the written blob
 111  * @param repo repository where to blob will be written
 112  * @param buffer data to be written into the blob
 113  * @param len length of the data
 114  * @return GIT_SUCCESS or an error code
 115  */
 116 GIT_EXTERN(int) git_blob_create_frombuffer(git_oid *oid, git_repository *repo, const void *buffer, size_t len);
 117
 118 /** @} */
 119 GIT_END_DECL
 120 #endif