Skip to content

Community

community::base_url

Accesses the base url (i.e. not including room or pubkey). Always lower-case/normalized.

Declaration

const std::string& base_url() const { return base_url_; }

Parameters

This endpoint takes no inputs.

Returns

  • const std::string& — Returns the base url

community::canonical_room

Takes a room token and returns it in canonical form (i.e. lower-cased). Throws std::invalid_argument if given an invalid room token (e.g. too long, or containing token other than a-z, 0-9, -, _).

Declaration

static std::string canonical_room(std::string_view room);

Parameters

  • room — string of the room token to construct the canonical room with

Returns

  • std::string — Returns the canonical room

community::canonical_url

Takes a base URL as input and returns it in canonical form. This involves doing things like lower casing it and removing redundant ports (e.g. :80 when using http://). Throws std::invalid_argument if given an invalid base URL.

Declaration

static std::string canonical_url(std::string_view url);

Parameters

  • url — string of the url to construct the canonical url with

Returns

  • std::string — Returns the canonical URL

community::canonicalize_room

Same as above canonical_room, but modifies the argument in-place instead of returning a modified copy.

Declaration

static void canonicalize_room(std::string& room);

Parameters

  • room — string of the room to modify to the canonical room

Returns

community::canonicalize_url

Same as above canonical_url, but modifies the argument in-place instead of returning a modified copy.

Declaration

static void canonicalize_url(std::string& url);

Parameters

  • url — string of the url to modify to the canonical url

Returns

community::full_url

Constructs and returns the full URL for this room. See below.

Declaration

std::string full_url() const;

Parameters

This endpoint takes no inputs.

Returns

  • std::string — Returns the Full URL

community::full_url(std::string_view,std::string_view,ustring_view)

Constructs and returns the full URL for a given base, room, and pubkey. Currently this returns it in a Session-compatibility form (https://server.com/RoomName?public_key=....), but future versions are expected to change to use (https://server.com/r/RoomName?public_key=...), which this library also accepts.

Declaration

static std::string full_url(
        std::string_view base_url, std::string_view room, ustring_view pubkey);

Parameters

  • base_url — string of the base url to construct the full url with
  • room — string of the room token to construct the full url with
  • pubkey — binary of the pubkey to construct the full url with

Returns

  • std::string — Returns the Full URL

community::parse_full_url

Takes a full room URL, splits it up into canonical url (see above), room, and server pubkey. We take both the deprecated form (e.g. https://example.com/SomeRoom?public_key=...) and new form (https://example.com/r/SomeRoom?public_key=...). The public_key is typically specified in hex (64 digits), but we also accept base64 (43 chars or 44 with padding) and base32z (52 chars) encodings (for slightly shorter URLs).

The returned URL is normalized (lower-cased, and cleaned up).

The returned room name is not normalized, that is, it preserve case.

Throw std::invalid_argument if anything in the URL is unparseable or invalid.

Declaration

static std::tuple<std::string, std::string, ustring> parse_full_url(std::string_view full_url);

Parameters

  • full_url — string of the url to parse

Returns

  • std::tuple — Tuple of 3 components of the url
    • std::string — canonical url, normalized
    • std::string — room name, not normalized
    • ustring — binary of the server pubkey

community::parse_partial_url

Takes a full or partial room URL (partial here meaning missing the ?public_key=...) and splits it up into canonical url, room, and (if present) pubkey.

Declaration

static std::tuple<std::string, std::string, std::optional<ustring>> parse_partial_url(
        std::string_view url);

Parameters

  • url — string of the url to parse

Returns

  • std::tuple — Tuple of 3 components of the url
    • std::string — canonical url, normalized
    • std::string — room name, not normalized
    • std::optional<ustring> — optional binary of the server pubkey if present

community::pubkey

Accesses the server pubkey (32 bytes).

Declaration

const ustring& pubkey() const { return pubkey_; }

Parameters

This endpoint takes no inputs.

Returns

  • const ustring& — Returns the pubkey

community::pubkey_b32z

Accesses the server pubkey as base32z (52 alphanumeric digits)

Declaration

std::string pubkey_b32z() const;

Parameters

This endpoint takes no inputs.

Returns

  • std::string — Returns the pubkey

community::pubkey_b64

Accesses the server pubkey as unpadded base64 (43 from alphanumeric, '+', and '/').

Declaration

std::string pubkey_b64() const;

Parameters

This endpoint takes no inputs.

Returns

  • std::string — Returns the pubkey

community::pubkey_hex

Accesses the server pubkey as hex (64 hex digits).

Declaration

std::string pubkey_hex() const;

Parameters

This endpoint takes no inputs.

Returns

  • std::string — Returns the pubkey

community::room

Accesses the room token; this is case-preserving, where possible. In some contexts, however, such as volatile info, the case is not preserved and this will always return the normalized (lower-case) form rather than the preferred form.

Declaration

const std::string& room() const { return localized_room_ ? *localized_room_ : room_; }

Parameters

This endpoint takes no inputs.

Returns

  • const std::string& — Returns the room token

community::room

Accesses the normalized room token, i.e. always lower-case.

Declaration

const std::string& room_norm() const { return room_; }

Parameters

This endpoint takes no inputs.

Returns

  • const std::string& — Returns the room token

community::set_base_url

Replaces the base_url of this object. Note that changing the URL and then giving it to set will end up inserting a new record but not removing the old one (you need to erase first to do that).

Declaration

void set_base_url(std::string_view new_url);

Parameters

  • new_url — URL to be stored

Returns

community::set_full_url

Replaces the baseurl/room/pubkey of this object from a URL. This parses the URL, then stores the values as if passed to set_base_url/set_room/set_pubkey.

The base URL will be normalized; the room name will be case-preserving (but see set_room for info on limitations on "case-preserving", particularly for volatile configs); and the embedded pubkey must be encoded in one of hex, base32z, or base64.

Declaration

void set_full_url(std::string_view full_url);

Parameters

  • full_url — URL to be stored

Returns

community::set_pubkey

Updates the pubkey of this community (typically this is not called directly but rather via set_server or during construction). Throws std::invalid_argument if the given pubkey does not look like a valid pubkey. The std::string_view version takes the pubkey as any of hex/base64/base32z.

NOTE: the pubkey of all communities with the same URLs are stored in common, so changing one community pubkey (and storing) will affect all communities using the same community base URL.

Declaration

void set_pubkey(ustring_view pubkey);
void set_pubkey(std::string_view pubkey);

Parameters

  • pubkey — Pubkey to be stored

Returns

community::set_room

Changes the room token. This stores (or updates) the name as given as the localized room, and separately stores the normalized (lower-case) token. Note that the localized name does not persist across a push or dump in some config contexts (such as volatile room info). If the new room given here changes more than just case (i.e. if the normalized room token changes) then a call to set will end up inserting a new record but not removing the old one (you need to erase first to do that).

Declaration

void set_room(std::string_view room);

Parameters

  • room — Room to be stored

Returns