Client functions and datatypes. More...

Collaboration diagram for Client:

Modules
	Caching
	Caching API supported by Concord.

	Commands
	Requests made by the client to the Gateway socket.

	Events
	Events sent over the Gateway socket to the client.

	Data Wrap
	Helpers for wrapping Discord data types for easier management.

	Timer
	Schedule callbacks to be called in the future.

Data Structures
struct	discord_config
	The Discord configuration handler. More...

struct	discord
	The Discord client handler. More...

Macros
#define	discord_claim(client, data) (__discord_claim(client, data), data)
	Claim ownership of a resource provided by Concord. More...

#define	ccord_global_init()

#define	ccord_global_cleanup()

#define	ccord_shutdown_async() discord_shutdown_all()
	Backwards compatible alias for discord_shutdown_all() More...

#define	discord_init discord_from_token
	Backwards compatible alias for discord_from_token() More...

#define	discord_config_init discord_from_json
	Backwards compatible alias for discord_from_json() More...

Functions
void	__discord_claim (struct discord client, const void data)

void	discord_unclaim (struct discord client, const void data)
	Unclaim ownership of a resource provided by Concord. More...

void	discord_shutdown_all (void)
	Gracefully notify all Discord connections for shutting down. More...

bool	discord_shutdown_all_ongoing (void)
	Check if all Discord connections shutting down is in progress. More...

struct discord *	discord_from_token (const char token[])
	Creates a Discord Client handle from a token. More...

struct discord *	discord_from_json (const char config_file[])
	Creates a Discord Client handle from a `config.json` file. More...

struct discord *	discord_from_config (const struct discord_config *config)
	Creates a Discord Client handle from a discord_config structure. More...

struct ccord_szbuf_readonly	discord_config_get_field (struct discord client, char const path[], unsigned depth)
	Get the contents from the config file field. More...

struct discord *	discord_clone (const struct discord *orig)
	Clone a discord client. More...

void	discord_cleanup (struct discord *client)
	Free a Discord Client handle. More...

const struct discord_user *	discord_get_self (struct discord *client)
	Get the client's cached user. More...

CCORDcode	discord_run (struct discord *client)
	Start a connection to the Discord Gateway. More...

void	discord_shutdown (struct discord *client)
	Gracefully shutdown an ongoing Discord connection. More...

void	discord_reconnect (struct discord *client, bool resume)
	Gracefully reconnects an ongoing Discord connection. More...

void *	discord_set_data (struct discord client, void data)
	Store user arbitrary data that can be retrieved by discord_get_data() More...

void *	discord_get_data (struct discord *client)
	Receive user arbitrary data stored with discord_set_data() More...

int	discord_get_ping (struct discord *client)
	Get the client WebSockets ping. More...

uint64_t	discord_timestamp (struct discord *client)
	Get the current timestamp (in milliseconds) More...

uint64_t	discord_timestamp_us (struct discord *client)
	Get the current timestamp (in microseconds) More...

struct logmod *	discord_get_logmod (struct discord *client)
	Retrieve client's logging module for configuration purposes. More...

struct io_poller *	discord_get_io_poller (struct discord *client)
	get the io_poller used by the discord client More...

Detailed Description

Client functions and datatypes.

Macro Definition Documentation

◆ discord_claim

#define discord_claim	(	client,
		data
	)	(__discord_claim(client, data), data)

Claim ownership of a resource provided by Concord.

See also: discord_unclaim()

Parameters

client	the client initialized with discord_from_token()
data	a resource provided by Concord

Returns: pointer to data (for one-liners)

◆ ccord_global_init

#define ccord_global_init ( )

Deprecated:: since v3.0.0, keep backwards compatibility

◆ ccord_global_cleanup

#define ccord_global_cleanup ( )

Deprecated:: since v3.0.0, keep backwards compatibility

◆ ccord_shutdown_async

#define ccord_shutdown_async ( ) discord_shutdown_all()

Backwards compatible alias for discord_shutdown_all()

Deprecated:: since v3.0.0

◆ discord_init

#define discord_init discord_from_token

Backwards compatible alias for discord_from_token()

Deprecated:: since v3.0.0

◆ discord_config_init

#define discord_config_init discord_from_json

Backwards compatible alias for discord_from_json()

Deprecated:: since v3.0.0

Function Documentation

◆ __discord_claim()

void __discord_claim	(	struct discord *	client,
		const void *	data
	)

◆ discord_unclaim()

void discord_unclaim	(	struct discord *	client,
		const void *	data
	)

Unclaim ownership of a resource provided by Concord.

Note: this will make the resource eligible for cleanup, so this should only be called when you no longer plan to use it

See also: discord_claim()

Parameters

client	the client initialized with discord_from_token()
data	a resource provided by Concord, that has been previously claimed with discord_claim()

Examples: cache.c.

◆ discord_shutdown_all()

void discord_shutdown_all ( void )

Gracefully notify all Discord connections for shutting down.

Note: this function will not wait before returning, and will return immediately. The shutdown process will be handled in the background.

◆ discord_shutdown_all_ongoing()

bool discord_shutdown_all_ongoing ( void )

Check if all Discord connections shutting down is in progress.

Returns: true if all shutdown is in progress, false otherwise

◆ discord_from_token()

struct discord * discord_from_token ( const char token[] )

Creates a Discord Client handle from a token.

See also: discord_get_logmod() to configure logging behavior

Parameters

token the bot token

Returns: the newly created Discord Client handle

Examples: webhook.c.

◆ discord_from_json()

struct discord * discord_from_json ( const char config_file[] )

Creates a Discord Client handle from a config.json file.

See also: discord_get_logmod() to configure logging behavior

Parameters

config_file the config.json file name

Returns: the newly created Discord Client handle

Examples: audit-log.c, ban.c, cache.c, channel.c, components.c, embed.c, emoji.c, fetch-messages.c, guild-template.c, guild.c, invite.c, manual-dm.c, pin.c, reaction.c, slash-commands.c, slash-commands2.c, and timers.c.

◆ discord_from_config()

struct discord * discord_from_config ( const struct discord_config * config )

Creates a Discord Client handle from a discord_config structure.

See also: discord_get_logmod() to configure logging behavior

Parameters

config the discord_config structure

Returns: the newly created Discord Client handle

◆ discord_config_get_field()

struct ccord_szbuf_readonly discord_config_get_field	(	struct discord *	client,
		char *const	path[],
		unsigned	depth
	)

Get the contents from the config file field.

Note: your bot MUST have been initialized with discord_from_json()

// Assume the following custom config.json field to be extracted
// "field": { "foo": "a string", "bar": 1234 }
 
...
struct ccord_szbuf_readonly value;
char foo[128];
long bar;
 
// field.foo
value = discord_config_get_field(client, (char *[2]){ "field", "foo" }, 2);
snprintf(foo, sizeof(foo), "%.*s", (int)value.size, value.start);
// field.bar
value = discord_config_get_field(client, (char *[2]){ "field", "bar" }, 2);
bar = strtol(value.start, NULL, 10);
 
printf("%s %ld", foo, bar); // "a string" 1234

Parameters

client	the client created with discord_from_json()
path	the JSON key path
depth	the path depth

Returns: a read-only sized buffer containing the field's contents

◆ discord_clone()

struct discord * discord_clone ( const struct discord * orig )

Clone a discord client.

Should be called before entering a thread, to ensure each thread has its own client instance with unique buffers, url and headers

Parameters

orig	the original client created with discord_from_token()

Returns: the client clone

◆ discord_cleanup()

void discord_cleanup ( struct discord * client )

Free a Discord Client handle.

Parameters

client the client created with discord_from_token()

Examples: audit-log.c, ban.c, cache.c, channel.c, components.c, embed.c, emoji.c, fetch-messages.c, guild-template.c, guild.c, invite.c, manual-dm.c, pin.c, reaction.c, slash-commands.c, slash-commands2.c, timers.c, and webhook.c.

◆ discord_get_self()

const struct discord_user * discord_get_self ( struct discord * client )

Get the client's cached user.

Parameters

client the client created with discord_from_token()

Warning: the returned structure should NOT be modified

◆ discord_run()

CCORDcode discord_run ( struct discord * client )

Start a connection to the Discord Gateway.

Parameters

client the client created with discord_from_token()

Returns: CCORDcode value for how the operation went, CCORD_OK means nothing out of the ordinary

Examples: audit-log.c, ban.c, cache.c, channel.c, components.c, embed.c, emoji.c, guild-template.c, guild.c, invite.c, manual-dm.c, pin.c, reaction.c, slash-commands.c, slash-commands2.c, and timers.c.

◆ discord_shutdown()

void discord_shutdown ( struct discord * client )

Gracefully shutdown an ongoing Discord connection.

Parameters

client the client created with discord_from_token()

◆ discord_reconnect()

void discord_reconnect	(	struct discord *	client,
		bool	resume
	)

Gracefully reconnects an ongoing Discord connection.

Parameters

client	the client created with discord_from_token()
resume	true to attempt to resume to previous session, false restart a fresh session

◆ discord_set_data()

void * discord_set_data	(	struct discord *	client,
		void *	data
	)

Store user arbitrary data that can be retrieved by discord_get_data()

Parameters

client	the client created with discord_from_token()
data	user arbitrary data

Returns: pointer to user data

Warning: the user should provide their own locking mechanism to protect its data from race conditions

◆ discord_get_data()

void * discord_get_data ( struct discord * client )

Receive user arbitrary data stored with discord_set_data()

Parameters

client the client created with discord_from_token()

Returns: pointer to user data

Warning: the user should provide their own locking mechanism to protect its data from race conditions

◆ discord_get_ping()

int discord_get_ping ( struct discord * client )

Get the client WebSockets ping.

Note: Only works after a connection has been established via discord_run()

Parameters

client the client created with discord_from_token()

Returns: the ping in milliseconds

◆ discord_timestamp()

uint64_t discord_timestamp ( struct discord * client )

Get the current timestamp (in milliseconds)

Parameters

client the client created with discord_from_token()

Returns: the timestamp in milliseconds

Examples: embed.c.

◆ discord_timestamp_us()

uint64_t discord_timestamp_us ( struct discord * client )

Get the current timestamp (in microseconds)

Parameters

client the client created with discord_from_token()

Returns: the timestamp in microseconds

◆ discord_get_logmod()

struct logmod * discord_get_logmod ( struct discord * client )

Retrieve client's logging module for configuration purposes.

See also: logmod.h

Parameters

client the client created with discord_from_token()

Returns: the client's logging manager

◆ discord_get_io_poller()

struct io_poller * discord_get_io_poller ( struct discord * client )

get the io_poller used by the discord client

Parameters

client the client created with discord_from_token()

Returns: struct io_poller*

Modules

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ discord_claim

◆ ccord_global_init

◆ ccord_global_cleanup

◆ ccord_shutdown_async

◆ discord_init

◆ discord_config_init

Function Documentation

◆ __discord_claim()

◆ discord_unclaim()

◆ discord_shutdown_all()

◆ discord_shutdown_all_ongoing()

◆ discord_from_token()

◆ discord_from_json()

◆ discord_from_config()

◆ discord_config_get_field()

◆ discord_clone()

◆ discord_cleanup()

◆ discord_get_self()

◆ discord_run()

◆ discord_shutdown()

◆ discord_reconnect()

◆ discord_set_data()

◆ discord_get_data()

◆ discord_get_ping()

◆ discord_timestamp()

◆ discord_timestamp_us()

◆ discord_get_logmod()

◆ discord_get_io_poller()