Concord - C Discord API library: Concord (original) (raw)

Concord Logo

discord-shield migrating-shield

🚨 Concord is not dead! 🚨

Development has been happening in the dev branch. We are working on new features and improvements. To access the latest version of the library, please check out the dev branch.

About

Concord is an asynchronous C99 Discord API library with minimal external dependencies, and a low-level translation of the Discord official documentation to C code.

Examples

The following are minimalistic examples, refer to for a better overview.*

Slash Commands (new method)

*Note: you need to replace GUILDID with an actual guild ID, or this example won't compile! You can use a macro to do this: #define GUILD_ID 1234567898765431

#include <string.h>

#include <concord/discord.h>

.description = "Ping command!"

};

GUILD_ID, &params, NULL);

}

return;

if (strcmp(event->data->name, "ping") == 0) {

.content = "pong"

}

};

event->token, &params, NULL);

}

}

int main(void) {

}

CCORDcode discord_create_guild_application_command(struct discord *client, u64snowflake application_id, u64snowflake guild_id, struct discord_create_guild_application_command *params, struct discord_ret_application_command *ret)

Create a new guild command.

CCORDcode discord_create_interaction_response(struct discord *client, u64snowflake interaction_id, const char interaction_token[], struct discord_interaction_response *params, struct discord_ret_interaction_response *ret)

Create a response to an Interaction from the gateway.

CCORDcode discord_run(struct discord *client)

Start a connection to the Discord Gateway.

struct discord * discord_init(const char token[])

Create a Discord Client handle by its token.

void discord_set_on_interaction_create(struct discord *client, void(*callback)(struct discord *client, const struct discord_interaction *event))

Triggers when user has used an interaction, such as an application command.

void discord_set_on_ready(struct discord *client, void(*callback)(struct discord *client, const struct discord_ready *event))

Triggers when the client session is ready.

@ DISCORD_INTERACTION_APPLICATION_COMMAND

Definition: interactions.h:24

@ DISCORD_INTERACTION_CHANNEL_MESSAGE_WITH_SOURCE

Definition: interactions.h:33

u64snowflake id

Definition: application.h:37

Definition: application_commands.h:254

char * name

Definition: application_commands.h:256

Definition: interactions.h:133

char * name

Definition: interactions.h:80

Definition: interactions.h:125

enum discord_interaction_callback_types type

Definition: interactions.h:127

Definition: interactions.h:48

u64snowflake id

Definition: interactions.h:50

struct discord_interaction_data * data

Definition: interactions.h:56

enum discord_interaction_types type

Definition: interactions.h:54

char * token

Definition: interactions.h:66

Definition: gateway.h:332

struct discord_application * application

Definition: gateway.h:345

The Discord client handler.

Definition: discord-internal.h:1190

Message Commands (old method)

#include <string.h>

#include <concord/discord.h>

#include <concord/log.h>

}

if (strcmp(event->content, "ping") == 0) {

}

}

int main(void) {

}

CCORDcode discord_create_message(struct discord *client, u64snowflake channel_id, struct discord_create_message *params, struct discord_ret_message *ret)

Post a message to a guild text or DM channel.

void discord_add_intents(struct discord *client, uint64_t code)

Subscribe to Discord Events.

void discord_set_on_message_create(struct discord *client, void(*callback)(struct discord *client, const struct discord_message *event))

Triggers when a message is created.

#define DISCORD_GATEWAY_MESSAGE_CONTENT

Definition: gateway.h:41

#define log_info(...)

Definition: log.h:52

Definition: channel.h:811

char * content

Definition: channel.h:813

Definition: channel.h:276

char * content

Definition: channel.h:288

u64snowflake channel_id

Definition: channel.h:280

struct discord_user * user

Definition: gateway.h:336

char * username

Definition: user.h:73

Supported operating systems (minimum requirements)

Note: big-endian processors running certain OSes like SPARC Solaris, PowerPC AIX, System Z z/OS or Linux, or MIPS IRIX are NOT supported. There are currently a few issues that prevent some of the logic from correctly on big-endian systems. This will be fixed soon.

Build Instructions

The only dependency is curl-7.56.1 or higher. If you are compiling libcurl from source, you will need to build it with SSL support.

On Windows

On Linux, BSD, and Mac OS X

*(note – # means that you should be running as root)*

Ubuntu and Debian

# apt update && apt install -y libcurl4-openssl-dev

Void Linux

# xbps-install -S libcurl-devel

Alpine

FreeBSD

OS X

Arch Linux / Manjaro (Arch based)

git clone https://aur.archlinux.org/concord-git.git

cd concord-git

makepkg -Acs

pacman -U concord-git-version-any.pkg.tar.zst

Alternatively, you can use an AUR helper:

Setting up your environment

Clone Concord into your workspace

$ git clone https://github.com/cogmasters/concord.git && cd concord

Compile Concord

Special notes for non-Linux systems

You might run into trouble with the compiler and linker not finding your Libcurl headers. You can do something like this:

$ CFLAGS=-I<some_path> LDFLAGS=-L<some_path> make

For instance, on a FreeBSD system:

$ CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib make

On OS X using MacPorts:

$ CFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib make

On OS X using a self-compiled libcurl:

$ CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/include make

On Windows with Cygwin, you might need to pass both arguments to use POSIX threading:

$ CFLAGS="-pthread -lpthread" make

Special note about linking Concord against another library

In some cases, you might want to link Concord into a shared object, or link it as a shared object into another shared object. In that case, you will need to compile Concord with CFLAGS="-fpic" make.

Configuring Concord

discord_config_init() is the initialization method that allows configuring your bot without recompiling.

The following outlines config.json fields:

{

"logging": { // logging directives

"level": "trace", // trace, debug, info, warn, error, fatal

"filename": "bot.log", // the log output file

"quiet": false, // change to true to disable logs in console

"overwrite": true, // overwrite file if already exists, append otherwise

"use_color": true, // display color for log entries

"http": {

"enable": true, // generate http specific logging

"filename": "http.log" // the HTTP log output file

},

"disable_modules": ["WEBSOCKETS", "USER_AGENT"] // disable logging for these modules

},

"discord": { // discord directives

"token": "YOUR-BOT-TOKEN", // replace with your bot token

"default_prefix": {

"enable": false, // enable default command prefix

"prefix": "YOUR-COMMANDS-PREFIX" // replace with your prefix

}

},

... // here you can add your custom fields *

}

Test Copycat-Bot

  1. Get your bot token and add it to config.json, by assigning it to discord's "token" field. There are well written instructions from discord-irc explaining how to get your bot token and adding it to a server.
  2. Build example executables:
  3. Run Copycat-Bot:
    $ cd examples && ./copycat

Get Copycat-Bot Response

Type a message in any channel the bot is part of and the bot should send an exact copy of it in return.

Terminate Copycat-Bot

With Ctrl+c or with Ctrl+|

Configure your build

The following outlines special flags and targets to override the default Makefile build with additional functionalities.

Special compilation flags

Example:

$ CFLAGS="-DCCORD_SIGINTCATCH -DCCORD_DEBUG_HTTP" make

Special targets

Installing Concord

*(note – # means that you should be running as root)*

This will install the headers and library files into $PREFIX. You can override this as such:

# PREFIX=/opt/concord make install

Cross-compiling Concord

To cross-compile Concord, see the manual here.

Included dependencies

The following are stable and well documented dependencies that are packaged with Concord and can be included to your projects:

File Description
cog-utils General purpose functions aimed at portability
log.c* A simple C99 logging library
carray* Macro-based implementation of type-safe arrays
anomap* Sorted key/value storage for C99
chash* Macro-based implementation of type-safe hashtables
json-build Tiny, zero-allocation JSON serializer
jsmn-find Tiny, zero-allocation JSON tokenizer

Note that included headers must be concord/ prefixed:

#include <concord/discord.h>

#include <concord/log.h>

Standalone executable

GCC

$ gcc myBot.c -o myBot -pthread -ldiscord -lcurl

Clang

$ clang myBot.c -o myBot -pthread -ldiscord -lcurl

UNIX C compilers

This includes the following compilers:

$ cc myBot.c -o myBot -ldiscord -lcurl -lpthread

Note: some systems such as Cygwin require you to do this:

$ gcc myBot.c -o myBot -pthread -lpthread -ldiscord -lcurl

(this links against libpthread.a in /usr/lib)

First, make sure your executable is compiled with the -g flag to ensure human-readable debugger messages.

Valgrind

Using valgrind to check for memory leaks:

valgrind --leak-check=full ./myBot

For a more comprehensive guide check Valgrind's Quick Start.

GDB

Using GDB to check for runtime errors, such as segmentation faults:

And then execute your bot from the gdb environment:

If the program has crashed, get a backtrace of the function calls leading to it:

For a more comprehensive guide check Beej's Quick Guide to GDB

Support

Problems? Check out our Discord Server

Contributing

All kinds of contributions are welcome, all we ask is to abide to our guidelines! If you want to help but is unsure where to get started then our Discord API Roadmap is a good starting point. Check our links for more helpful information.

Getting Started