/* **********************************************************
 * Copyright 2010 VMware, Inc.  All rights reserved.
 * **********************************************************/

/*
 * @VMKAPIMOD_LICENSE@
 */

/*
 ***********************************************************************
 * String                                                         */ /**
 * \addtogroup Lib
 * @{
 * \defgroup String Interfaces
 *
 * @{
 ***********************************************************************
 */

#ifndef _VMKAPI_STRING_H_
#define _VMKAPI_STRING_H_

/** \cond never */
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
#error This vmkapi file should never be included directly but only via vmkapi.h
#endif
/** \endcond never */

#include <stdarg.h>


/*
 ***********************************************************************
 * vmk_StringCat --                                               */ /**
 *
 * \brief Appends the source string to the end of the destination string. 
 *
 * \note  This function will not block.
 *
 * \param[in] dst    String to copy to.
 * \param[in] src    String to append from.
 * \param[in] dstLen Length of destination buffer.
 *
 * \note dst will always be nul terminated so long as dstLen is greater
 *       than zero.
 *
 * \retval VMK_OK             The string was successfully concatenated.
 * \retval VMK_LIMIT_EXCEEDED The source string was too long to be
 *                            copied fully into the destination.  As
 *                            much of the source string as possible was
 *                            concatenated.
 * \retval VMK_BAD_PARAM      The source string or destination buffer
 *                            is not valid.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_StringCat(
   char *dst,
   const char *src,
   vmk_ByteCount dstLen);

/*
 ***********************************************************************
 * vmk_StringCopy --                                              */ /**
 *
 * \brief Copy a string up to a maximum number of bytes.
 *
 * \param[out] dst      String to copy to.
 * \param[in]  src      String to copy from.
 * \param[in]  dstLen   Maximum number of bytes to copy into dst.
 *
 * \note dst will always be be nul terminated so long as dstLen is
 *       greater than zero.
 * \note  This function will not block.
 *
 * \retval VMK_OK             The string was successfully copied.
 * \retval VMK_LIMIT_EXCEEDED The source string was too long to be
 *                            copied fully into the destination.  As
 *                            much of the source string as possible was
 *                            copied.
 * \retval VMK_BAD_PARAM      The source string or destination buffer
 *                            is not valid.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_StringCopy(
   char *dst,
   const char *src,
   vmk_ByteCount dstLen);

/*
 ***********************************************************************
 * vmk_StringLCopy --                                             */ /**
 *
 * \brief Copy a string and ensure nul termination.
 *
 * \param[out] dst    String to copy to.
 * \param[in]  src    String to copy from.
 * \param[in]  dstLen Maximum number of bytes to store a string in dst.
 * \param[out] outLen Number of bytes necessary.  Optional: may pass
 *                    NULL.
 *
 * \note dst will always be be nul terminated so long as dstLen is
 *       greater than zero.
 * \note outLen will always be set to the number of bytes needed to
 *       successfully copy the src string, even if that copy is not
 *       successful, not including the nul terminator.
 * \note  This function will not block.
 *
 * \retval VMK_OK             The string was successfully copied.
 * \retval VMK_LIMIT_EXCEEDED The source string was too long to be
 *                            copied fully into the destination.  As
 *                            much of the source string as possible was
 *                            copied.
 * \retval VMK_BAD_PARAM      The source string or destination buffer
 *                            is not valid.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_StringLCopy(
   char *dst,
   const char *src,
   vmk_ByteCount dstLen,
   vmk_ByteCount *outLen);

/*
 ***********************************************************************
 * vmk_StringFormat --                                            */ /**
 *
 * \brief Formats the provided format string and arguments into the
 *        destination buffer, up to a maximum bound.
 *
 * \param[in]  str      Buffer in which to place output.
 * \param[in]  strLen   Maximum number of bytes to output.
 * \param[out] outLen   Number of bytes necessary to format this string,
 *                      not including the terminating nul character.
 *                      Optional: may pass NULL.
 * \param[in]  format   Printf-style format string.
 *
 * \note str will always be be nul terminated so long as strLen is
 *       greater than zero.
 * \note outLen will always be set to the number of bytes needed to
 *       successfully format the src string, even if that formatting
 *       is not successful, not including the nul terminator.
 * \printformatstringdoc
 * \note  This function will not block.
 *
 * \retval VMK_OK             The string was successfully formatted.
 * \retval VMK_LIMIT_EXCEEDED The source string was too long to be
 *                            formatted fully into the destination.  As
 *                            much of the specified format string as
 *                            possible was formatted.
 * \retval VMK_BAD_PARAM      The format string or destination buffer
 *                            is not valid.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_StringFormat(
   char *str,
   vmk_ByteCount strLen,
   vmk_ByteCount *outLen,
   const char *format,
   ...)
VMK_ATTRIBUTE_PRINTF(4,5);

/*
 ***********************************************************************
 * vmk_StringVFormat --                                            */ /**
 *
 * \brief Formats the provided format string and varargs into the
 *        destination buffer, up to a maximum bound.
 *
 * \param[in]  str      Buffer in which to place output.
 * \param[in]  strLen   Maximum number of bytes to output.
 * \param[out] outLen   Number of bytes necessary to format this string,
 *                      not including the terminating nul character.
 *                      Optional: may pass NULL.
 * \param[in]  format   Printf-style format string.
 * \param[in]  ap       Varargs for format.
 *
 * \note str will always be be nul terminated so long as strLen is
 *       greater than zero.
 * \note outLen will always be set to the number of bytes needed to
 *       successfully format the src string, even if that formatting
 *       is not successful, not including the nul terminator.
 * \printformatstringdoc
 * \note  This function will not block.
 *
 * \retval VMK_OK             The string was successfully formatted.
 * \retval VMK_LIMIT_EXCEEDED The source string was too long to be
 *                            formatted fully into the destination.  As
 *                            much of the specified format string as
 *                            possible was formatted.
 * \retval VMK_BAD_PARAM      The format string or destination buffer
 *                            is not valid.
 *
 ***********************************************************************
 */
VMK_ReturnStatus vmk_StringVFormat(
   char *str,
   vmk_ByteCount strLen,
   vmk_ByteCount *outLen,
   const char *format,
   va_list ap);

#endif /* _VMKAPI_STRING_H_ */
/** @} */
/** @} */