kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/cxx/common/kzip_writer_c_api.h (about)

     1  /*
     2   * Copyright 2018 The Kythe Authors. All rights reserved.
     3   *
     4   * Licensed under the Apache License, Version 2.0 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   *   http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  #ifndef KYTHE_CPP_COMMON_KZIP_WRITER_C_API_H_
    18  #define KYTHE_CPP_COMMON_KZIP_WRITER_C_API_H_
    19  
    20  /// /brief This is a C API wrapper for kythe::KZipWriter.
    21  ///
    22  /// Used for linking to non-C languages such as Rust.  This is a partial API,
    23  /// which is enough to write out basic files and compilation units.
    24  
    25  #include <stddef.h>
    26  #include <stdint.h>
    27  
    28  #ifdef __cplusplus
    29  extern "C" {
    30  #endif  // __cplusplus
    31  
    32  #define KZIP_WRITER_ENCODING_JSON (1)
    33  #define KZIP_WRITER_ENCODING_PROTO (2)
    34  #define KZIP_WRITER_ENCODING_ALL \
    35    (KZIP_WRITER_ENCODING_JSON | KZIP_WRITER_ENCODING_PROTO)
    36  
    37  #define KZIP_WRITER_BUFFER_TOO_SMALL_ERROR (-1)
    38  #define KZIP_WRITER_PROTO_PARSING_ERROR (-2)
    39  
    40  /// \brief The opaque kzip writer object.
    41  struct KzipWriter;
    42  
    43  /// \brief Creates a new kzip writer.
    44  /// \param path The path to the file to create.
    45  /// \param path_len the string length of path, required due to the C API.
    46  /// \param encoding The compilation unit encoding, either
    47  ///        KZIP_WRITER_ENCODING_JSON, or KZIP_WRITER_ENCODING_PROTO
    48  /// \param create_status zero if created fine, nonzero in case of an error.
    49  ///        Positive error values are the same as in absl::Status.  Negative
    50  ///        error values are either KZIP_WRITER_BUFFER_TOO_SMALL_ERROR, or
    51  ///        KZIP_WRITER_PROTO_PARSING_ERROR.
    52  /// Caller takes the ownership of the returned pointer.  KzipWriter_Close must
    53  /// be called to release the memory.
    54  struct KzipWriter* KzipWriter_Create(const char* path, const size_t path_len,
    55                                       int32_t encoding, int32_t* create_status);
    56  
    57  /// \brief Deallocates KzipWriter.
    58  ///
    59  /// Must be called once KzipWriter is no longer needed.
    60  void KzipWriter_Delete(struct KzipWriter* writer);
    61  
    62  /// \brief Closes the writer.
    63  /// Must be called before destroying the object.
    64  int32_t KzipWriter_Close(struct KzipWriter* writer);
    65  
    66  /// \brief Writes a piece of content into the kzip, returning a digest.
    67  ///
    68  /// The content is
    69  /// specified using both the pointer to the beginning and the size.  The caller
    70  /// must provide a buffer to put the digest into, and a buffer size.  Nonzero
    71  /// status is returned in case of an error writing.  Specifically, if there is
    72  /// insufficient space in the buffer, KZIP_WRITER_BUFFER_TOO_SMALL_ERROR is
    73  /// returned.
    74  /// \param writer The writer to write into.
    75  /// \param content The file content buffer to write.
    76  /// \param content_length The length of the buffer to write.
    77  /// \param digest_buffer The output buffer to store the digest into.  Must be
    78  ///        large enough to hold a digest.  The buffer is NOT NUL-terminated.
    79  /// \param buffer_length The length of digest_buffer in bytes.
    80  int32_t KzipWriter_WriteFile(struct KzipWriter* writer, const char* content,
    81                               const size_t content_length, char* digest_buffer,
    82                               size_t buffer_length,
    83                               size_t* resulting_digest_size);
    84  
    85  /// \brief Writes a compilation unit into the kzip, returning a digest.
    86  //
    87  /// The caller must provide a buffer to put the digest into, and a buffer size.
    88  /// Nonzero status is returned in case of an error while writing.  The result
    89  /// in the buffer is NOT NUL-terminated.
    90  int32_t KzipWriter_WriteUnit(struct KzipWriter* writer, const char* proto,
    91                               size_t proto_length, char* digest_buffer,
    92                               size_t buffer_length,
    93                               size_t* resulting_digest_size);
    94  
    95  #ifdef __cplusplus
    96  }  // extern "C"
    97  #endif  // __cplusplus
    98  
    99  #endif  // KYTHE_CPP_COMMON_KZIP_WRITER_C_API_H_