/*
 * Copyright (c) 2020 Red Hat, Inc.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA. 
 *
 * $Id: //eng/uds-releases/jasper/src/uds/chapterIndex.h#4 $
 */

#ifndef CHAPTER_INDEX_H
#define CHAPTER_INDEX_H 1

#include "deltaIndex.h"
#include "geometry.h"

enum {
  // The value returned as the record page number when an entry is not found
  // in the chapter index.
  NO_CHAPTER_INDEX_ENTRY  = -1
};

typedef struct openChapterIndex {
  const Geometry *geometry;
  DeltaIndex      deltaIndex;
  uint64_t        virtualChapterNumber;
  bool            headerNativeEndian;
  uint64_t        volumeNonce;
} OpenChapterIndex;


/**
 * Make a new open chapter index.
 *
 * @param openChapterIndex  Location to hold new open chapter index pointer
 * @param geometry                        The geometry
 * @param chapterIndexHeaderNativeEndian  chapter index header format
 * @param volumeNonce                     The volume nonce.
 *
 * @return error code or UDS_SUCCESS
 **/
int makeOpenChapterIndex(OpenChapterIndex **openChapterIndex,
                         const Geometry    *geometry,
                         bool               chapterIndexHeaderNativeEndian,
                         uint64_t           volumeNonce)
  __attribute__((warn_unused_result));

/**
 * Terminate and clean up an open chapter index.
 *
 * @param openChapterIndex  The open chapter index to terminate
 **/
void freeOpenChapterIndex(OpenChapterIndex *openChapterIndex);

/**
 * Empty an open chapter index, and prepare it for writing a new virtual
 * chapter.
 *
 * @param openChapterIndex      The open chapter index to empty
 * @param virtualChapterNumber  The virtual chapter number
 **/
void emptyOpenChapterIndex(OpenChapterIndex *openChapterIndex,
                           uint64_t          virtualChapterNumber);

/**
 * Create a new record in an open chapter index, associating a chunk name with
 * the number of the record page containing the metadata for the chunk.
 *
 * @param openChapterIndex  The open chapter index
 * @param name              The chunk name
 * @param pageNumber        The number of the record page containing the name
 *
 * @return UDS_SUCCESS or an error code
 **/
int putOpenChapterIndexRecord(OpenChapterIndex   *openChapterIndex,
                              const UdsChunkName *name,
                              unsigned int        pageNumber)
  __attribute__((warn_unused_result));

/**
 * Pack a section of an open chapter index into a chapter index page.  A
 * range of delta lists (starting with a specified list index) is copied
 * from the open chapter index into a memory page.  The number of lists
 * copied onto the page is returned to the caller.
 *
 * @param openChapterIndex  The open chapter index
 * @param memory            The memory page to use
 * @param firstList         The first delta list number to be copied
 * @param lastPage          If true, this is the last page of the chapter
 *                          index and all the remaining lists must be packed
 *                          onto this page
 * @param numLists          The number of delta lists that were copied
 *
 * @return error code or UDS_SUCCESS.  On UDS_SUCCESS, the numLists
 *         argument contains the number of lists copied.
 **/
int packOpenChapterIndexPage(OpenChapterIndex *openChapterIndex,
                             byte             *memory,
                             unsigned int      firstList,
                             bool              lastPage,
                             unsigned int     *numLists)
  __attribute__((warn_unused_result));

/**
 * Get the number of records in an open chapter index.
 *
 * @param openChapterIndex  The open chapter index
 *
 * @return The number of records
 **/
int getOpenChapterIndexSize(OpenChapterIndex *openChapterIndex)
  __attribute__((warn_unused_result));

/**
 * Get the number of bytes allocated for the open chapter index.
 *
 * @param openChapterIndex  The open chapter index
 *
 * @return the number of bytes allocated
 **/
size_t getOpenChapterIndexMemoryAllocated(OpenChapterIndex *openChapterIndex);

/**
 * Make a new chapter index page, initializing it with the data from the
 * given buffer.
 *
 * @param chapterIndexPage  The new chapter index page
 * @param geometry          The geometry
 * @param indexPage         The memory page to use
 * @param volumeNonce       If non-zero, the volume nonce to verify
 *
 * @return UDS_SUCCESS or an error code
 **/
int initializeChapterIndexPage(DeltaIndexPage *chapterIndexPage,
                               const Geometry *geometry,
                               byte           *indexPage,
                               uint64_t        volumeNonce)
  __attribute__((warn_unused_result));

/**
 * Validate a chapter index page.  This is called at rebuild time to ensure
 * that the volume file contains a coherent chapter index.
 *
 * @param chapterIndexPage  The chapter index page
 * @param geometry          The geometry of the volume
 *
 * @return The result code:
 *         UDS_SUCCESS for a good chapter index page
 *         UDS_CORRUPT_COMPONENT if the chapter index code detects invalid data
 *         UDS_CORRUPT_DATA if there is a problem in a delta list bit stream
 *         UDS_BAD_STATE if the code follows an invalid code path
 **/
int validateChapterIndexPage(const DeltaIndexPage *chapterIndexPage,
                             const Geometry       *geometry)
  __attribute__((warn_unused_result));

/**
 * Search a chapter index page for a chunk name, returning the record page
 * number that may contain the name.
 *
 * @param [in]  chapterIndexPage    The chapter index page
 * @param [in]  geometry            The geometry of the volume
 * @param [in]  name                The chunk name
 * @param [out] recordPagePtr       The record page number
 *                                  or NO_CHAPTER_INDEX_ENTRY if not found
 *
 * @return UDS_SUCCESS or an error code
 **/
int searchChapterIndexPage(DeltaIndexPage     *chapterIndexPage,
                           const Geometry     *geometry,
                           const UdsChunkName *name,
                           int                *recordPagePtr)
  __attribute__((warn_unused_result));

#endif /* CHAPTER_INDEX_H */