TTDT_MESSAGE_ACCEPT(3)

💅 ttdt_message_accept — accept a contract to handle a ToolTalk request

okay bestie, this one is from the library call manual — the header vibe is literally ttdt_message_accept(library call), but we're folding that in right here so you don't have to squint at a header line. It's all about letting a tool accept a contract to handle a ToolTalk request. periodt 💖

✨ NAME ✨

ttdt_message_accept — accept a contract to handle a ToolTalk request. That's the whole name, no cap. 🎀

🌸 SYNOPSIS 🌸

#include &<Tt/tttk.h>
Tt_pattern *ttdt_message_accept(
Tt_message contract,
Ttdt_contract_cb cb,
Widget shell,
void *clientdata,
int accept,
int sendStatus);

🦋 DESCRIPTION 🦋

So here's the tea: ttdt_message_accept registers in the default session for TT_HANDLER-addressed requests, and those requests come in three little groups:

1. Get_Geometry, Set_Geometry, Get_Iconified, Set_Iconified, Get_Mapped, Set_Mapped, Raise, Lower, Get_XInfo
2. Pause, Resume
3. Quit, Get_Status

If the shell argument is not NULL, the ToolTalk service handles messages in (1) transparently; otherwise, it treats them like messages in (3). slay ✨

If shell is non-NULL and cb is NULL, then the ToolTalk service handles messages in (2) transparently by passing shell and the appropriate boolean value to XtSetSensitive(3). If cb is NULL, then the ToolTalk service treats messages in (2) like (3).

If cb is not NULL, ttdt_message_accept passes messages in (3) to the cb callback; otherwise it fails with TT_DESKTOP_ENOTSUP. iykyk 🫶

If accept is True, ttdt_message_accept calls tt_message_accept(3) with a contract argument. If contract has a returned value from tt_message_status of TT_WRN_START_MESSAGE, it is the message that caused the tool to be started. The tool should join any scopes it wants to serve before accepting contract, so that it will receive any other messages already dispatched to its ptype. Otherwise, those messages will cause other instances of the ptype to be started. If that is in fact desired (for example, because the tool can only service one message at a time), then the tool should undeclare its ptype while it is busy. big main character energy 👑

If sendStatus is True, ttdt_message_accept sends a Status notice to the requester, using the arguments (if any) passed to ttdt_open. 💌

💖 RETURN VALUE 💖

Upon successful completion, the ttdt_message_accept function returns a null-terminated array of Tt_pattern, and associates this array with contract; otherwise, it returns an error pointer. The application can use tt_ptr_error(3) to extract one of the following Tt_status values from the returned handle:

• TT_ERR_NOMP — The ttsession(1) process is not running and the ToolTalk service cannot restart it.
• TT_ERR_POINTER — The pointer passed does not point to an object of the correct type for this operation.
• TT_ERR_UNIMP — The ttsession(1) for the default session is of a version that does not support tt_message_accept. If contract is a TT_WRN_START_MESSAGE, messages to the tool's ptype will remain blocked until contract is rejected, replied to, or failed.

not the error-pointer jumpscare 😭 but at least now you know what each one means. 💅

🎀 APPLICATION USAGE 🎀

The ttdt_message_accept function is what a tool calls when it wants to accept responsibility for handling (that is, failing or rejecting) a request.

If contract is destroyed by tttk_message_destroy(3), then the patterns will also be destroyed. Otherwise, the caller is responsible for iterating over the array and destroying each pattern. cleanup era 🧚

🌈 EXAMPLES 🌈

See ttdt_session_join(3) for an example of a Ttdt_contract_cb callback that can be used with ttdt_message_accept. go look, bestie 🍓

⭐ SEE ALSO ⭐

• Tt/tttk.h - Tttttk(5)
• ttdt_open(3)
• ttmedia_ptype_declare(3)
• tt_ptype_declare(3)
• ttdt_session_join(3)
• ttdt_file_join(3)
• tt_ptype_undeclare(3)
• XtSetSensitive(3)

---

byeee bestie 🫶 — footer check: the page closes with ttdt_message_accept(library call), and that's the library-call footer tag we're leaving you with. mwah 💋✨