TT_FILE_OBJECTS_QUERY(3)

💅 tt_file_objects_query — the "find every object in this file" era

ok so real talk: this is a library call page (like, section 3 energy, tt_file_objects_query(library call) if you're being formal about it) and it's about asking the ToolTalk service to go rummage around in a file and hand you back every object it finds. bestie, it's giving ✨inventory vibes✨ and honestly the way it works is so clean. let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <Tt/tt_c.h>
Tt_status tt_file_objects_query(
const char *filepath,
Tt_filter_function filter,
void *context,
void *accumulator);

---

🌸 DESCRIPTION 🌸

okay so tt_file_objects_query is literally you telling the ToolTalk service: "girl, go find all the objects in the named file and pass the objids to my filter function." and the context pointer and accumulator pointer you gave it up front? those get passed along to the filter function too. everyone's invited to the group chat 💬

the way that it works is: as the ToolTalk service finds each object, it calls your filter function, passing it the objid of that object plus the two application-supplied pointers (yep, context and accumulator, the iconic duo). then your filter does its little computation and returns a Tt_filter_action value, which is basically the filter tapping the query function on the shoulder and going "keep going" or "bestie stop". 🛑

the Tt_filter_action values are, in order:

• TT_FILTER_CONTINUE — the query function should continue. keep it moving, no thoughts just vibes ➡️
• TT_FILTER_STOP — the query function should stop. that's it, that's the whole message, we're done here ✋

and now the arguments, one by one, no gatekeeping:

• filepath — the name of the file to be searched for objects. this is the target, the main character, the file in question 📁
• filter — the filter function to which the objids are to be passed. like, this is the callback that eats objids for breakfast 🍓
• context — a pointer to any information the filter needs to execute. heads up: the ToolTalk service does not interpret this argument, it just passes it directly to the filter function. it's a courier, not a critic 💌
• accumulator — a pointer to where the filter is to store the results of the query and filter operations. same deal here: the ToolTalk service does not interpret this argument, it passes it directly to the filter function. no questions asked, no notes 👑

---

💖 RETURN VALUE 💖

upon successful completion, tt_file_objects_query returns the status of the operation as one of these Tt_status values. get you a function that can return all of these:

• TT_OK — the operation completed successfully. slay!! 🎉 the good ending.
• TT_ERR_DBAVAIL — the ToolTalk service could not access the ToolTalk database needed for this operation. the database said "new phone who dis" 😭
• TT_ERR_DBEXIST — the ToolTalk service could not access the specified ToolTalk database in the expected place. she checked where it was supposed to be and… nobody home 💀
• TT_ERR_NOMP — the ttsession(1) process is not running and the ToolTalk service cannot restart it. no session, no service, no vibes 🙈
• TT_ERR_PATH — the specified pathname included an unsearchable directory. the path was giving locked door energy 🚪🔒
• TT_WRN_STOPPED — the query operation being performed was halted by Tt_filter_function. that's a warning not an error, your filter just called it early, respect the decision 💅

ngl, TT_WRN_STOPPED is technically a TT_WRN_* not a TT_ERR_* — so don't panic when you see it, it's literally just "your filter said stop". periodt.

---

🦋 SEE ALSO 🦋

• Tt/tt_c.h - Tttt_c(5). iykyk — go read the header page for the full lore 📚

---

and that's the whole page, bestie — no cap 🌈 this was tt_file_objects_query(library call), straight from the library call pages, and that footer line up top-duplicated-down-low is just the same tt_file_objects_query(library call) stamp doing its little encore at the bottom. go find those objects, you're gonna ate 💜✨🎀