ZHTTP_REQUEST(3)

📦
version 4.2.1 · 7 versions
, in fedora 44, ubuntu resolute, ubuntu stonking

🦋 ZHTTP_REQUEST(3) — a CZMQ manual page, bestie edition 🦋

okay so. this is the manual page for ZHTTP_REQUEST(3), straight out of the CZMQ Manual, and we're gonna get you all the way together on it. no gatekeeping, no vibes of mystery. just us, a request class, and a whole lot of draft-API energy. 💅

✨ NAME ✨

zhttp_request — it's the class for a zhttp server request. that's the whole name section, short and sweet, we love a minimal queen. 🎀

✨ SYNOPSIS ✨

okay bestie, before literally anything else, the big warning:

This is a draft class, and may change without notice. It is disabled in stable builds by default. If you use this in applications, please ask for it to be pushed to stable state. Use --enable-drafts to enable.

so basically it's giving 🚧 under construction 🚧 and it's all wrapped in #ifdef CZMQ_BUILD_DRAFT_API, iykyk. here's the whole thing, verbatim, do not touch the code:

//  This is a draft class, and may change without notice. It is disabled in
//  stable builds by default. If you use this in applications, please ask
//  for it to be pushed to stable state. Use --enable-drafts to enable.
#ifdef CZMQ_BUILD_DRAFT_API
//  *** Draft method, for development use, may change without warning ***
//  Create a new http request.
CZMQ_EXPORT zhttp_request_t *
    zhttp_request_new (void);

//  *** Draft method, for development use, may change without warning ***
//  Destroy an http request.
CZMQ_EXPORT void
    zhttp_request_destroy (zhttp_request_t **self_p);

//  *** Draft method, for development use, may change without warning ***
//  Receive a new request from zhttp_server.
//  Return the underlying connection if successful, to be used when calling zhttp_response_send.
CZMQ_EXPORT void *
    zhttp_request_recv (zhttp_request_t *self, zsock_t *sock);

//  *** Draft method, for development use, may change without warning ***
//  Send a request to zhttp_client.
//  Url and the request path will be concatenated.
//  This behavior is useful for url rewrite and reverse proxy.
//
//  Send also allow two user provided arguments which will be returned with the response.
//  The reason for two, is to be able to pass around the server connection when forwarding requests or both a callback function and an arg.
CZMQ_EXPORT int
    zhttp_request_send (zhttp_request_t *self, zhttp_client_t *client, int timeout, void *arg, void *arg2);

//  *** Draft method, for development use, may change without warning ***
//  Get the request method
CZMQ_EXPORT const char *
    zhttp_request_method (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Set the request method
CZMQ_EXPORT void
    zhttp_request_set_method (zhttp_request_t *self, const char *method);

//  *** Draft method, for development use, may change without warning ***
//  Get the request url.
//  When receiving a request from http server this is only the path part of the url.
CZMQ_EXPORT const char *
    zhttp_request_url (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Set the request url
//  When sending a request to http client this should be full url.
CZMQ_EXPORT void
    zhttp_request_set_url (zhttp_request_t *self, const char *url);

//  *** Draft method, for development use, may change without warning ***
//  Get the request content type
CZMQ_EXPORT const char *
    zhttp_request_content_type (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Set the request content type
CZMQ_EXPORT void
    zhttp_request_set_content_type (zhttp_request_t *self, const char *content_type);

//  *** Draft method, for development use, may change without warning ***
//  Get the content length of the request
CZMQ_EXPORT size_t
    zhttp_request_content_length (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Get the headers of the request
CZMQ_EXPORT zhash_t *
    zhttp_request_headers (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Get the content of the request.
CZMQ_EXPORT const char *
    zhttp_request_content (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Get the content of the request.
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT char *
    zhttp_request_get_content (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Set the content of the request.
//  Content must by dynamically allocated string.
//  Takes ownership of the content.
CZMQ_EXPORT void
    zhttp_request_set_content (zhttp_request_t *self, char **content);

//  *** Draft method, for development use, may change without warning ***
//  Set the content of the request..
//  The content is assumed to be constant-memory and will therefore not be copied or deallocated in any way.
CZMQ_EXPORT void
    zhttp_request_set_content_const (zhttp_request_t *self, const char *content);

//  *** Draft method, for development use, may change without warning ***
//  Set the content to NULL
CZMQ_EXPORT void
    zhttp_request_reset_content (zhttp_request_t *self);

//  *** Draft method, for development use, may change without warning ***
//  Match the path of the request.
//  Support wildcards with '%s' symbol inside the match string.
//  Matching wildcards until the next '/', '?' or '\0'.
//  On successful match the variadic arguments will be filled with the matching strings.
//  On successful match the method is modifying the url field and break it into substrings.
//  If you need to use the url, do it before matching or take a copy.
//
//  User must not free the variadic arguments as they are part of the url.
//
//  To use the percent symbol, just double it, e.g "%%something".
//
//  Example:
//  if (zhttp_request_match (request, "POST", "/send/%s/%s", &name, &id))
CZMQ_EXPORT bool
    zhttp_request_match (zhttp_request_t *self, const char *method, const char *path, ...);

//  *** Draft method, for development use, may change without warning ***
//  Self test of this class.
CZMQ_EXPORT void
    zhttp_request_test (bool verbose);

#endif // CZMQ_BUILD_DRAFT_API
Please add '@interface' section in './../src/zhttp_request.c'.

and yes, that last line really is just sitting there in the synopsis, asking someone to please add an @interface section in ./../src/zhttp_request.c. iconic honestly. the docs are doing their own to-do list. 📝

🌸 what each lil function does 🌸

so every single one of these is marked * Draft method, for development use, may change without warning *. they're all drafts. all of them. periodt.

  • zhttp_request_new (void) — create a brand new http request. fresh out the box. returns zhttp_request_t *.
  • zhttp_request_destroy (zhttp_request_t **self_p) — destroy an http request. note the double pointer, she takes self_p, not self. 💀
  • zhttp_request_recv (zhttp_request_t *self, zsock_t *sock) — receive a new request from zhttp_server. it returns the underlying connection if it worked, and you use that when you call zhttp_response_send. returns void *.
  • zhttp_request_send (zhttp_request_t *self, zhttp_client_t *client, int timeout, void *arg, void *arg2) — send a request to zhttp_client. the url and the request path get concatenated, which is lowkey the whole point: it's useful for url rewrite and reverse proxy. it also lets you pass two user provided arguments which come back with the response. why two, you ask? because you need to pass around the server connection when forwarding requests, or both a callback function and an arg. returns int.
  • zhttp_request_method (zhttp_request_t *self) — get the request method. returns const char *.
  • zhttp_request_set_method (zhttp_request_t *self, const char *method) — set the request method.
  • zhttp_request_url (zhttp_request_t *self) — get the request url. heads up: when you're receiving a request from the http server, this is only the path part of the url. returns const char *.
  • zhttp_request_set_url (zhttp_request_t *self, const char *url) — set the request url. and when you're sending a request to the http client, this should be the full url. don't mix those up bestie, that's a whole vibe check fail. 🚩
  • zhttp_request_content_type (zhttp_request_t *self) — get the request content type. returns const char *.
  • zhttp_request_set_content_type (zhttp_request_t *self, const char *content_type) — set the request content type.
  • zhttp_request_content_length (zhttp_request_t *self) — get the content length of the request. returns size_t.
  • zhttp_request_headers (zhttp_request_t *self) — get the headers of the request. returns zhash_t *.
  • zhttp_request_content (zhttp_request_t *self) — get the content of the request. returns const char *.
  • zhttp_request_get_content (zhttp_request_t *self) — also gets the content of the request, but this one's different: the caller owns the return value and must destroy it when done. returns char *. you break it, you buy it. 🫶
  • zhttp_request_set_content (zhttp_request_t *self, char **content) — set the content of the request. the content must be a dynamically allocated string, and this call takes ownership of it. so don't you dare free it after. 😭
  • zhttp_request_set_content_const (zhttp_request_t *self, const char *content) — set the content of the request. (yes, the original has two dots there, "request..", we're keeping her exactly as she is 💅) the content is assumed to be constant-memory, so it will not be copied or deallocated in any way.
  • zhttp_request_reset_content (zhttp_request_t *self) — set the content to NULL. that's it. that's the function.
  • zhttp_request_match (zhttp_request_t *self, const char *method, const char *path, ...) — match the path of the request. this one is the ✨main character✨ so let's take our time:
    • it supports wildcards with the '%s' symbol inside the match string.
    • it matches wildcards until the next '/', '?' or '\0'.
    • on a successful match, the variadic arguments get filled with the matching strings.
    • on a successful match, the method is modifying the url field and breaks it into substrings. so if you need to use the url, do it before matching, or take a copy. no cap, it will rearrange your url on you. 🙈
    • the user must not free the variadic arguments, because they're part of the url.
    • to use the percent symbol, just double it, like "%%something".
    • example, straight from the source:
if (zhttp_request_match (request, "POST", "/send/%s/%s", &name, &id))
  • zhttp_request_test (bool verbose) — self test of this class. go off, queen. 🧪

✨ DESCRIPTION ✨

zhttp_request — zhttp server request. and the lil glow-up detail: the class can be reused. ♻️ so it's not a one-and-done situation, she comes back.

then, again, the source itself is begging: Please add @discuss section in ./../src/zhttp_request.c. someone get on that fr fr.

✨ EXAMPLE ✨

From zhttp_request_test method.

and then… the example section contains this absolute gem:

Please add '@selftest' section in './../src/zhttp_request.c'.

so the example is currently a placeholder asking for a selftest section. we're manifesting it. ✨🔮✨

✨ AUTHORS ✨

The czmq manual was written by the authors in the AUTHORS file. collective slay, we love a group project that actually got finished. 👑

✨ RESOURCES ✨

Main web site:

Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>

(that [1] is doing a lil footnote number thing, it comes back at the bottom, we'll get there 🎀)

Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

so yeah: MPL v. 2.0, respect her. 📜💜

✨ NOTES ✨

  1. zeromq-dev@lists.zeromq.org mailto:zeromq-dev@lists.zeromq.org

there she is. the footnote. the girl from [1]. mystery solved bestie. 🕵️‍♀️🌸

and that's the whole page, start to finish, no skips, no cuts.

signing off with the receipts: this is CZMQ 4.2.1, dated 01/16/2026, and the page name is ZHTTP_REQUEST(3). take care of her, she's a draft. 💖✨🦋🎀🫶

📦 where this page comes from