/*
 * Ibis - IRCv3 Library
 * Copyright (C) Ibis Developers
 *
 * Ibis is the legal property of its developers, whose names are too numerous to
 * list here. Please refer to the COPYRIGHT file distributed with this source
 * distribution.
 *
 * This library 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 library 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 library; if not, see <https://www.gnu.org/licenses/>.
 */

#if !defined(IBIS_GLOBAL_HEADER_INSIDE) && !defined(IBIS_COMPILATION)
# error "only <ibis.h> may be included directly"
#endif

#ifndef IBIS_BATCH_H
#define IBIS_BATCH_H

#include <glib.h>

#include <glib-object.h>

#include "ibismessage.h"
#include "ibisversion.h"

G_BEGIN_DECLS

#define IBIS_BATCH_ADD_MESSAGE_ERROR ibis_batch_add_message_error_quark()

/**
 * ibis_batch_add_message_error_quark:
 *
 * The error domain to identify errors when adding messages to a batch.
 *
 * Returns: The error domain.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
GQuark ibis_batch_add_message_error_quark(void);

/**
 * IbisBatchAddMessageError:
 * @IBIS_BATCH_ADD_MESSAGE_ERROR_INVALID_REFERENCE_TAG: the specified reference
 *  tag did not match the reference tag of the batch.
 *
 * Errors returned from [method@Batch.add_message].
 *
 * Since: 0.12
 */
typedef enum {
	IBIS_BATCH_ADD_MESSAGE_ERROR_INVALID_REFERENCE_TAG,
} IbisBatchAddMessageError;

#define IBIS_BATCH_PARSE_ERROR ibis_batch_parse_error_quark()

/**
 * ibis_batch_parse_error_quark:
 *
 * The error domain to identify errors when parsing a batch.
 *
 * Returns: The error domain.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
GQuark ibis_batch_parse_error_quark(void);

/**
 * IbisBatchParseError:
 * @IBIS_BATCH_PARSE_ERROR_NOT_ENOUGH_PARAMS: batch messages must have at least
 *  two parameters. The reference tag and the batch type.
 * @IBIS_BATCH_PARSE_ERROR_INVALID_REFERENCE_TAG: the reference tag must start
 *  with a '+' and have at least one additional character.
 * @IBIS_BATCH_PARSE_ERROR_INVALID_BATCH_TYPE: the specified batch type was
 *  invalid.
 *
 * Errors returned from [ctor@Batch.parse].
 *
 * Since: 0.12
 */
typedef enum {
	IBIS_BATCH_PARSE_ERROR_NOT_ENOUGH_PARAMS,
	IBIS_BATCH_PARSE_ERROR_INVALID_REFERENCE_TAG,
	IBIS_BATCH_PARSE_ERROR_INVALID_BATCH_TYPE,
} IbisBatchParseError;

#define IBIS_TYPE_BATCH (ibis_batch_get_type())

/**
 * IbisBatch:
 *
 * An implementation of batches as defined by
 * https://ircv3.net/specs/extensions/batch.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
G_DECLARE_FINAL_TYPE(IbisBatch, ibis_batch, IBIS, BATCH, GObject)

/**
 * ibis_batch_add_message:
 * @message: (transfer none): the message to add
 * @error: (out) (optional): a return address for a #GError
 *
 * Adds a message to the batch.
 *
 * If the message is not tagged with the same reference tag as the batch,
 * @error will be set and false will be returned.
 *
 *
 * Returns: true on success.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
gboolean ibis_batch_add_message(IbisBatch *batch, IbisMessage *message, GError **error);

/**
 * ibis_batch_get_batch_type:
 *
 * Gets the type of the batch.
 *
 * Returns: the type of the batch.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
const char *ibis_batch_get_batch_type(IbisBatch *batch);

/**
 * ibis_batch_get_parent_tag:
 *
 * Gets the parent tag of the batch.
 *
 * Returns: (nullable): The reference tag of the parent batch if there is one.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
const char *ibis_batch_get_parent_tag(IbisBatch *batch);

/**
 * ibis_batch_get_reference_tag:
 *
 * Gets the reference tag of the batch.
 *
 * Returns: The reference tag of the batch.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
const char *ibis_batch_get_reference_tag(IbisBatch *batch);

/**
 * ibis_batch_is_end:
 * @message: a message
 *
 * Checks if a message is the end of a batch and returns the reference tag.
 *
 * Returns: (nullable): The reference tag if the message is the end of a batch.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
const char *ibis_batch_is_end(IbisMessage *message);

/**
 * ibis_batch_parse: (constructor)
 * @message: a batch message
 * @error: (out) (optional): a return address for a #GError
 *
 * Creates a batch from a batch message.
 *
 * Returns: (transfer full) (nullable): The new batch on success, otherwise
 *          null with @error possibly set.
 *
 * Since: 0.12
 */
IBIS_AVAILABLE_IN_0_12
IbisBatch *ibis_batch_parse(IbisMessage *message, GError **error);

G_END_DECLS

#endif /* IBIS_BATCH_H */
