Utility

mg_call()

void mg_call(struct mg_connection *c, int ev, void *ev_data);

Send ev event to c event handler. This function is useful then implementing your own protocol.

Parameters:

• c - Connection to send event
• ev - Event to send
• ev_data - Additional event parameter

Return value: None

Usage example:

// In a timer callback, send MG_EV_USER event to all connections
static void timer_fn(void *arg) {
  struct mg_mgr *mgr = (struct mg_mgr *) arg;
  for (struct mg_connection *c = mgr->conns; c != NULL; c = c->next) {
    mg_call(c, MG_EV_USER, "hi!");
  }
}

mg_error()

void mg_error(struct mg_connection *c, const char *fmt, ...);

Send MG_EV_ERROR to connection event handler with error message formatted using printf semantics.

Parameters:

• c - Connection to send event
• fmt - Format string in printf semantics

Return value: None

Usage example:

mg_error(c, "Operation failed, error code: %d", errno);

mg_md5_init()

void mg_md5_init(mg_md5_ctx *c);

Initialize context for MD5 hashing.

Parameters:

• c - Pointer to mg_md5_ctx structure to initialize

Return value: None

Usage example:

mg_md5_ctx ctx;
mg_md5_init(&ctx);

mg_md5_update()

void mg_md5_update(mg_md5_ctx *c, const unsigned char *data, size_t len);

Hash len bytes of data pointed by data using MD5 algorithm.

Parameters:

• c - MD5 context
• data - Data to hash
• len - Data length

Return value: None

Usage example:

mg_md5_ctx ctx;
// Context initialization
// ...

mg_md5_update(&ctx, "data", 4);       // hash "data" string
mg_md5_update(&ctx, "more data", 9);  // hash "more data" string

mg_md5_final()

void mg_md5_final(mg_md5_ctx *c, unsigned char buf[16]);

Get current MD5 hash for context.

Parameters:

• c - MD5 context
• buf - Pointer to buffer to write MD5 hash value

Return value: None

Usage example:

mg_md5_ctx ctx;
// Context initialization
// ...

unsigned char buf[16];
mg_md5_final(&ctx, buf);  // `buf` is now MD5 hash

mg_sha1_init()

void mg_sha1_init(mg_sha1_ctx *c);

Initialize context for calculating SHA1 hash

Parameters:

• c - pointer to mg_sha1_ctx structure to initialize

Return value: none

Usage example:

mg_sha1_ctx ctx;
mg_sha1_init(&ctx);

mg_sha1_update()

void mg_sha1_update(mg_sha1_ctx *c, const unsigned char *data, size_t len);

Hash len bytes of data using SHA1 algorithm.

Parameters:

• c - SHA1 context
• data - Data to hash
• len - Data length

Return value: None

Usage example:

mg_sha1_ctx ctx;
// Context initialization
// ...

mg_sha1_update(&ctx, "data", 4);      // hash "data" string
mg_sha1_update(&ctx, "more data", 9); // hash "more data" string

mg_sha1_final()

void mg_sha1_final(unsigned char digest[20], mg_sha1_ctx *c);

Get current SHA1 hash for context.

Parameters:

• c - SHA1 context
• digest - Pointer to buffer to receive hash value

Return value: None

Usage example:

mg_sha1_ctx ctx;
// Context initialization
// ...

unsigned char buf[20];
mg_sha1_final(buf, &ctx); // `buf` is now SHA1 hash

mg_base64_update()

size_t mg_base64_update(unsigned char p, char *buf, size_t len);

Encode p byte to base64 and write result into buf buffer

Parameters:

• p - Byte to encode
• buf - Pointer to buffer to write result
• len - Buffer length

Return value: Number of chars written into buffer

Usage example:

char buf[10];
mg_base64_update((unsigned char)"a", buf, 10); // Encode "a" into base64 and write it to buf

mg_base64_final()

size_t mg_base64_final(char *buf, size_t len);

Add base64 finish mark and \0 symbol to buf

Parameters:

• buf - Pointer to buffer to write finish mark
• len - Buffer length

Return value: Number of chars written into buffer

char buf[10];
// ...

mg_base64_final(buf, 10);

mg_base64_encode()

size_t mg_base64_encode(const unsigned char *p, size_t n, char *buf, size_t len);

Encode n bytes data pointed to by p using base64 and write result into buf.

Parameters:

• p - Pointer to data to encode
• n - Data length
• buf - Pointer to buffer to write result
• len - Buffer length

Return value: Number of chars written into buffer

Usage example:

char buf[128];
mg_base64_encode((uint8_t *) "abcde", 5, buf, 128); // buf is now YWJjZGU=

mg_base64_decode()

size_t mg_base64_decode(const char *src, size_t n, char *dst, size_t len);

Decode n bytes of base64-ed src and write it to dst.

Parameters:

• src - Data to decode
• n - Data length
• dst - Pointer to output buffer
• len - Buffer length

Return value: Number of chars written into buffer

Usage example:

char buf[128];
mg_base64_decode("Q2VzYW50YQ==", 12, buf, 128); // buf is now "Cesanta"

mg_random()

bool mg_random(void *buf, size_t len);

Fill in buffer buf, len with random data. Note: Mongoose uses this function for TLS and some other routines that require RNG (random number generator). It is possible to override a built-in mg_random() by specifying a MG_ENABLE_CUSTOM_RANDOM=1 build preprocessor constant.

Parameters:

• buf - Pointer to buffer to receive random data
• len - Buffer size

Return value: This function returns false when the system rand() has to be used, because a stronger PRNG for the configured MG_ARCH could not be found.

Usage example:

char buf[10];
mg_random(buf, sizeof(buf)); // `buf` is now random bytes

mg_random_str()

char *mg_random_str(char *buf, size_t len);

Fill in buffer buf, len with random alphanumeric characters: a-zA-Z0-9. A buffer is zero-terminated.

Parameters:

• buf - a pointer to a buffer
• len - a buffer size

Return value: buf value.

Usage example:

char buf[10];
printf("Random: %s\n", mg_random_str(buf, sizeof(buf)));

mg_ntohs()

uint16_t mg_ntohs(uint16_t net);

Convert uint16_t value to host order.

Parameters:

• net - 16-bit value in network order

Return value: 16-bit value in host order

Usage example:

uint16_t val = mg_ntohs(0x1234);

mg_ntohl()

uint32_t mg_ntohl(uint32_t net);

Convert uint32_t value to host order.

Parameters:

• net - 32-bit value in network order

Return value: 32-bit value in host order

Usage example:

uint32_t val = mg_ntohl(0x12345678);

mg_htons()

uint16_t mg_htons(uint16_t h);

Convert uint16_t value to network order.

Parameters:

• h - 16-bit value in host order

Return value: 16-bit value in network order

Usage example:

uint16_t val = mg_htons(0x1234);

mg_htonl()

uint32_t mg_ntohl(uint32_t h);

Convert uint32_t value to network order.

Parameters:

• h - 32-bit value in host order

Return value: 32-bit value in network order

Usage example:

uint32_t val = mg_htonl(0x12345678);

mg_crc32()

uint32_t mg_crc32(uint32_t crc, const char *buf, size_t len);

Calculate CRC32 checksum for a given buffer. An initial crc value should be 0.

Parameters:

• crc - Initial CRC value
• buf - Data to calculate CRC32
• len - Data size

Return value: Calculated CRC32 checksum

Usage example:

char data[] = "hello";
uint32_t crc = mg_crc32(0, data, sizeof(data));

mg_check_ip_acl()

int mg_check_ip_acl(struct mg_str acl, struct mg_addr *remote_ip);

Check IP address remote_ip against the IP ACL acl.

Currently, only the IPv4 address format is supported for the ACL string.

Parameters:

• acl - an ACL string, e.g. -0.0.0.0/0,+1.2.3.4
• remote_ip - an IP address

Return value: 1 if remote_ip is allowed, 0 if not, and <0 if acl is invalid

Usage example:

if (mg_check_ip_acl(mg_str("-0.0.0.0/0,+1.2.3.4"), c->rem) != 1) {
  LOG(LL_INFO, ("NOT ALLOWED!"));
}

mg_url_decode()

int mg_url_decode(const char *src, size_t src_len, char *dst, size_t dst_len, int form);

Decode URL-encoded string s and write it into to buffer.

Parameters:

• src - String to decode
• src_len - Length of the string to decode
• dst - Pointer to output buffer
• dst_len - Output buffer size
• form - If non-zero, then + is decoded as whitespace.

Return value: Decoded bytes count or negative value on error

Usage example:

char url[] = "eexample.org%2Ftest";
char buf[1024];
mg_url_encode(url, sizeof(url) - 1, buf, sizeof(buf), 0); // buf is now "example.org/test"

mg_url_encode

size_t mg_url_encode(const char *s, size_t n, char *buf, size_t len);

Encode s string to URL-encoding and write encoded string into buf.

Parameters:

• s - String to encode
• n - String to encode length
• buf - Output buffer
• len - Output buffer size

Return value: Number of characters written to buf

Usage example:

char url[] = "example.org/test";
char buf[1024];
mg_url_encode(url, sizeof(url) - 1, buf, sizeof(buf)); // buf is now "example.org%2Ftest"

mg_modbus_listen

struct mg_modbus_req {
  uint8_t func;      // Function code, one of MG_MODBUS_FUNC_*
  uint8_t error;     // Error code user handler can set
  uint16_t addr;     // Address
  union {
    bool *bits;
    uint16_t *regs;
  } u;
  uint16_t len;      // Number of registers or bits
};

struct mg_connection *mg_modbus_listen(struct mg_mgr *mgr, const char *url,
                                       mg_event_handler_t fn, void *fn_data);

Start Modbus-TCP listener. See modbus.h for function and error codes. When a Modbus-TCP request arrives, Mongoose calls

Parameters:

• mgr - Event manager
• url - Listening URL
• fn - Event handler function. Should catch MG_EV_MODBUS_REQ and process struct mg_modbus_req * passed as ev_data
• fn_fata - Arbitrary user data

Return value: listening connection or NULL

Usage example:

static void modbus_ev_handler(struct mg_connection *c, int ev, void *ev_data) {
  if (ev == MG_EV_MODBUS_REQ) {
    struct mg_modbus_req *mr = (struct mg_modbus_req *) ev_data;
    if (mr->func == MG_MODBUS_FUNC_READ_COILS) {
      for (uint16_t i = 0; i < mr->len; i++) {
        mr->u.bits[i] = 1;
      }
    } else {
      mr->error = MG_MODBUS_ERR_DEVICE_FAILURE;
    }
  }
}

/// ...
mg_modbus_listen(&g_mgr, "tcp://0.0.0.0:502", modbus_ev_handler, NULL);