/* Copyright 2006 Garrett Rooney.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file etl_error.h
 * @brief Functions for manipulating ETL exception objects
 */

#ifndef ETL_ERROR_H
#define ETL_ERROR_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
 * Check if the @c etl_error_t returned by @a expression is equal to
 * @c ETL_SUCCESS.  If it is, do nothing, if not, then return it.
 */
#define ETL_ERR(expression) do {                \
          etl_error_t *etl__err = (expression); \
          if (etl__err)                         \
            return etl__err;                    \
        } while (0)

/** A low level error code. */
typedef int etl_status_t;

/** Successful return value for a function that returns @c etl_error_t. */
#define ETL_SUCCESS NULL

/** The available buffer space was exhausted. */
#define ETL_ENOSPACE -1

/** The file in question did not exist. */
#define ETL_ENOENT   -2

/** The input was invalid. */
#define ETL_EINVAL   -3

/** The requested functionality has not been implemented. */
#define ETL_ENOTIMPL -4

/** The I/O operation in question failed. */
#define ETL_EIO      -5

/** An exception object. */
typedef struct {
  /** The underlying status code. */
  etl_status_t err;

  /** A human readable error message. */
  const char *msg;

  /** The line on which the error occurred. */
  uint32_t line;

  /** The file in which the error occurred. */
  const char *file;
} etl_error_t;

/**
 * Return a new @c etl_error_t with underlying @c etl_status_t @a err
 * and message @a msg.
 */
#define etl_error_create(err, msg) etl_error_create_impl(err,      \
                                                         msg,      \
                                                         __LINE__, \
                                                         __FILE__)

/**
 * The underlying function that implements @c etl_error_create.
 *
 * This is an implementation detail, and should not be directly called
 * by users.
 */
etl_error_t *
etl_error_create_impl(etl_status_t err,
                      const char *msg,
                      uint32_t line,
                      const char *file);

/**
 * Return a new @c etl_error_t with underlying @c etl_status_t @a err
 * and message created @c printf style with @a fmt and varargs.
 */
#define etl_error_createf(err, fmt, ...) etl_error_createf_impl(err,         \
                                                                __LINE__,    \
                                                                __FILE__,    \
                                                                fmt,         \
                                                                __VA_ARGS__)

/**
 * The underlying function that implements @c etl_error_createf.
 *
 * This is an implementation detail, and should not be directly called
 * by users.
 */
etl_error_t *
etl_error_createf_impl(etl_status_t err,
                       uint32_t line,
                       const char *file,
                       const char *fmt,
                       ...);

/** Destroy @a err. */
void etl_error_clear(etl_error_t *err);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* ETL_ERROR_H */