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.

	Timer
	Schedule callbacks to be called in the future.

Data Structures
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...

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...

struct discord *	discord_init (const char token[])
	Create a Discord Client handle by its token. More...

struct discord *	discord_config_init (const char config_file[])
	Create a Discord Client handle by a `config.json` file. 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 logconf *	discord_get_logconf (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_init()
data	a resource provided by Concord

Returns: pointer to data (for one-liners)

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_init()
data	a resource provided by Concord, that has been previously claimed with discord_claim()

Examples: cache.c.

◆ discord_init()

struct discord * discord_init ( const char token[] )

Create a Discord Client handle by its token.

See also: discord_get_logconf() to configure logging behavior

Parameters

token the bot token

Returns: the newly created Discord Client handle

Examples: webhook.c.

◆ discord_config_init()

struct discord * discord_config_init ( const char config_file[] )

Create a Discord Client handle by a config.json file.

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_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_config_init()

// 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_config_init()
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_init()

Returns: the client clone

◆ discord_cleanup()

void discord_cleanup ( struct discord * client )

Free a Discord Client handle.

Parameters

client the client created with discord_init()

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_init()

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_init()

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_init()

◆ discord_reconnect()

void discord_reconnect	(	struct discord *	client,
		bool	resume
	)

Gracefully reconnects an ongoing Discord connection.

Parameters

client	the client created with discord_init()
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_init()
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_init()

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_init()

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_init()

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_init()

Returns: the timestamp in microseconds

◆ discord_get_logconf()

struct logconf * discord_get_logconf ( struct discord * client )

Retrieve client's logging module for configuration purposes.

See also: logconf_setup(), logconf_set_quiet(), logconf_set_level()

Parameters

client the client created with discord_init()

Returns: the client's logging module

◆ 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_init()

Returns: struct io_poller*

Modules

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ discord_claim

Function Documentation

◆ __discord_claim()

◆ discord_unclaim()

◆ discord_init()

◆ discord_config_init()

◆ 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_logconf()

◆ discord_get_io_poller()