/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */

#ifndef __C_PUSH_CONSUMER_H__
#define __C_PUSH_CONSUMER_H__

#include "CCommon.h"
#include "CMessageExt.h"

#ifdef __cplusplus
extern "C" {
#endif

// typedef struct _CConsumer_ _CConsumer;
typedef struct CPushConsumer CPushConsumer;

typedef enum E_CConsumeStatus { E_CONSUME_SUCCESS = 0, E_RECONSUME_LATER = 1 } CConsumeStatus;

typedef int (*MessageCallBack)(CPushConsumer*, CMessageExt*);

ROCKETMQCLIENT_API CPushConsumer* CreatePushConsumer(const char* groupId);
// 创建一个消费者实例并返回指向该实例的指针。
// 参数：groupId - 消费者所属的消费者组ID。
// 必要性：是必须的，创建消费者实例时必须提供消费者组ID。

ROCKETMQCLIENT_API int DestroyPushConsumer(CPushConsumer* consumer);
// 销毁指定的消费者实例。
// 参数：consumer - 需要销毁的消费者实例。
// 必要性：在消费者不再需要时调用，以释放资源。

ROCKETMQCLIENT_API int StartPushConsumer(CPushConsumer* consumer);
// 启动消费者，开始消费消息。
// 参数：consumer - 要启动的消费者实例。
// 必要性：启动消费者并开始接收消息是必须的。

ROCKETMQCLIENT_API int ShutdownPushConsumer(CPushConsumer* consumer);
// 关闭消费者，停止消费消息。
// 参数：consumer - 要关闭的消费者实例。
// 必要性：在应用程序结束时，必须调用该函数来安全地关闭消费者。

ROCKETMQCLIENT_API const char* ShowPushConsumerVersion(CPushConsumer* consumer);
// 获取当前消费者实例的版本信息。
// 参数：consumer - 需要获取版本信息的消费者实例。
// 必要性：不是必须的，但可以用于调试和确认消费者版本。

ROCKETMQCLIENT_API int SetPushConsumerGroupID(CPushConsumer* consumer, const char* groupId);
// 设置消费者的消费者组ID。
// 参数：consumer - 消费者实例；groupId - 消费者组ID。
// 必要性：用于设置消费者的消费者组ID，必须设置。

ROCKETMQCLIENT_API const char* GetPushConsumerGroupID(CPushConsumer* consumer);
// 获取消费者实例的消费者组ID。
// 参数：consumer - 消费者实例。
// 必要性：不是必须的，但可以用于检查当前的消费者组ID。

ROCKETMQCLIENT_API int SetPushConsumerNameServerAddress(CPushConsumer* consumer, const char* namesrv);
// 设置消费者的 NameServer 地址。
// 参数：consumer - 消费者实例；namesrv - NameServer 地址。
// 必要性：必须配置，以便消费者能够连接到 RocketMQ NameServer。

ROCKETMQCLIENT_API int SetPushConsumerNameServerDomain(CPushConsumer* consumer, const char* domain);
// 设置消费者的 NameServer 域名。
// 参数：consumer - 消费者实例；domain - NameServer 域名。
// 必要性：不是必须的，通常会使用 SetPushConsumerNameServerAddress 设置 IP 地址。

ROCKETMQCLIENT_API int Subscribe(CPushConsumer* consumer, const char* topic, const char* expression);
// 订阅一个指定的 topic 和 tag。
// 参数：consumer - 消费者实例；topic - 消息主题；expression - 消息标签（可以为空，表示订阅所有标签）。
// 必要性：必须配置消费者要订阅的 topic。

ROCKETMQCLIENT_API int RegisterMessageCallbackOrderly(CPushConsumer* consumer, MessageCallBack pCallback);
// 注册顺序消息的回调函数。
// 参数：consumer - 消费者实例；pCallback - 消息回调函数。
// 必要性：如果需要顺序消费消息，则需要使用此函数注册顺序消息回调。

ROCKETMQCLIENT_API int RegisterMessageCallback(CPushConsumer* consumer, MessageCallBack pCallback);
// 注册异步消息的回调函数。
// 参数：consumer - 消费者实例；pCallback - 消息回调函数。
// 必要性：必须配置回调函数，以便消费者能够处理收到的消息。

ROCKETMQCLIENT_API int UnregisterMessageCallbackOrderly(CPushConsumer* consumer);
// 注销顺序消息的回调函数。
// 参数：consumer - 消费者实例。
// 必要性：不是必须的，只有在不再需要顺序消息时调用。

ROCKETMQCLIENT_API int UnregisterMessageCallback(CPushConsumer* consumer);
// 注销异步消息的回调函数。
// 参数：consumer - 消费者实例。
// 必要性：不是必须的，只有在不再需要处理消息时调用。

ROCKETMQCLIENT_API int SetPushConsumerThreadCount(CPushConsumer* consumer, int threadCount);
// 设置消费者的线程数量。
// 参数：consumer - 消费者实例；threadCount - 消费者线程数量。
// 必要性：用于控制消费者处理消息的并发度。如果不设置，默认值通常为1。

ROCKETMQCLIENT_API int SetPushConsumerMessageBatchMaxSize(CPushConsumer* consumer, int batchSize);
// 设置消费者最大批量消息大小。
// 参数：consumer - 消费者实例；batchSize - 最大批量消息大小。
// 必要性：不是必须的，只有在需要调整消息消费的批量大小时才使用。

ROCKETMQCLIENT_API int SetPushConsumerInstanceName(CPushConsumer* consumer, const char* instanceName);
// 设置消费者实例名称。
// 参数：consumer - 消费者实例；instanceName - 消费者实例名称。
// 必要性：不是必须的，可以为空，默认使用系统生成的实例名。

ROCKETMQCLIENT_API int SetPushConsumerSessionCredentials(CPushConsumer* consumer,
                                                         const char* accessKey,
                                                         const char* secretKey,
                                                         const char* channel);
// 设置消费者的身份验证信息。
// 参数：consumer - 消费者实例；accessKey - 访问密钥；secretKey - 密钥；channel - 渠道。
// 必要性：在需要身份验证的环境下（如阿里云RocketMQ），此项配置是必须的。


// 设置消费者日志文件路径
// 功能：设置日志文件的存储路径。消费者在运行时会将日志信息写入该路径指定的文件。
// 必要性：日志路径配置有助于在生产环境中追踪和调试消费者的行为，记录日志是运维管理中的重要环节。
ROCKETMQCLIENT_API int SetPushConsumerLogPath(CPushConsumer* consumer, const char* logPath);


// 设置日志文件的数量和每个文件的最大大小
// 功能：设置日志文件的数量和每个日志文件的最大大小。超过最大大小时会创建新日志文件。
// 必要性：控制日志文件的数量和大小有助于防止日志文件过大，占用过多磁盘空间。对于高频消息消费的场景，合理配置日志文件大小和数量至关重要。
ROCKETMQCLIENT_API int SetPushConsumerLogFileNumAndSize(CPushConsumer* consumer, int fileNum, long fileSize);


// 设置消费者的日志级别
// 功能：设置消费者的日志级别（如 DEBUG, INFO, WARN, ERROR 等），控制输出的日志详细程度。
// 必要性：日志级别配置可以帮助调节日志的详细程度，根据环境不同选择适当的日志级别（例如，生产环境使用 ERROR 级别，开发环境使用 DEBUG 级别）。
ROCKETMQCLIENT_API int SetPushConsumerLogLevel(CPushConsumer* consumer, CLogLevel level);


// 设置消息模型（广播模式或集群模式）
// 功能：设置消费者的消息消费模型。广播模式（`CMessageModel::BROADCASTING`）会将消息推送到所有消费者，而集群模式（`CMessageModel::CLUSTERING`）则只会将消息推送到一个消费者。
// 必要性：选择消息模型对消息消费的行为有直接影响，集群模式适用于负载均衡，而广播模式适用于所有消费者都需要接收消息的场景。
ROCKETMQCLIENT_API int SetPushConsumerMessageModel(CPushConsumer* consumer, CMessageModel messageModel);


// 设置消费者最大缓存消息大小（以字节为单位）
// 功能：设置消费者最大缓存消息的大小。当缓存达到此大小时，消费者会停止消费，直到缓存被处理并清空。
// 必要性：此配置对于高吞吐量场景非常重要，它可以防止消费者在消息积压时出现内存溢出，保证消费者稳定运行。
ROCKETMQCLIENT_API int SetPushConsumerMaxCacheMessageSize(CPushConsumer* consumer, int maxCacheSize);


// 设置消费者最大缓存消息大小（以 MB 为单位）
// 功能：与 `SetPushConsumerMaxCacheMessageSize` 类似，不过该参数以 MB 为单位，设置最大缓存消息的大小。
// 必要性：提供 MB 级别的配置对于一些需要调整内存和消息缓存的应用场景，能够更加精细地控制内存使用情况。
ROCKETMQCLIENT_API int SetPushConsumerMaxCacheMessageSizeInMb(CPushConsumer* consumer, int maxCacheSizeInMb);


// 设置消息追踪模型
// 功能：设置消息的追踪模式。开启追踪会记录消费者的消费信息，帮助开发者分析消息的流转和消费情况。
// 必要性：对于消息的追踪和监控至关重要，尤其在故障排查和性能优化中，可以通过追踪记录分析消费者的消息处理状态。
ROCKETMQCLIENT_API int SetPushConsumerMessageTrace(CPushConsumer* consumer, CTraceModel openTrace);


#ifdef __cplusplus
}
#endif
#endif  //__C_PUSH_CONSUMER_H__
