ESTNODE(3)

📦 version 1.4.13, in fedora 43, fedora 44

👑 estnode.h — the node API of Hyper Estraier 👑

okay bestie so this is ESTNODE(3), straight outta the Hyper Estraier manual, and it's literally the whole node API. it's giving "networking but make it cute". grab a snack, we're going through every single function, no skips, no cap. 🍓

✨ SYNOPSIS ✨

#include <estraier.h>
#include <estnode.h>
#include <cabin.h>
#include <stdlib.h>

like, include all four, obviously. 💅

🌸 API FOR INITIALIZING 🌸

so before you do literally anything with the node API, you gotta initialize the network environment at the start of your program. and then — and this is the part people forget — you gotta free that environment at the end. it's giving "clean up after yourself, queen". 🧚

est_init_net_env

this one initializes the networking environment. it's the opening act. 🌈

int est_init_net_env(void);
  • the return value is true if it worked, and false if it didn't. lowkey simple.
  • it's allowable to call this function multiple times — so if you're chaotic like that, you do you — but the catch is you then have to call est_free_net_env at the same frequency. one free per init, bestie, keep the receipts. 🧾

est_free_net_env

the closer. the goodbye. the cleanup era. 💖

void est_free_net_env(void);
  • there is no parameter and no return value. it just does the thing. iconic.

🦋 API FOR NODES 🦋

okay so here's the whole vibe: the structure type ESTNODE is for abstraction of connection to a node. a node has its own URL, because of course it does, main character energy. ⭐

no entity of ESTNODE is accessed directly — you access it by the pointer. periodt.

so when we say node connection object, we mean the pointer and its referent. that's the whole thing.

  • a node connection object is created by est_node_new
  • and destroyed by est_node_delete
  • every created node connection object should be destroyed 🚨 like, all of them. don't leave them hanging.

est_node_new

creates a node connection object. the birth. the origin story. 🌱

ESTNODE *est_node_new(const char *url);
  • url specifies the URL of a node.
  • the return value is a node connection object.

est_node_delete

destroys a node connection object. rip boo, you served. 💀🫶

void est_node_delete(ESTNODE *node);
  • node specifies a node connection object.

est_node_set_proxy

sets the proxy information of a node connection object. going through a middleman, we love a middleman. 🙈

void est_node_set_proxy(ESTNODE *node, const char *host, int port);
  • node specifies a node connection object.
  • host specifies the host name of a proxy server.
  • port specifies the port number of the proxy server.

est_node_set_timeout

sets the timeout of a connection. so it doesn't just sit there waiting forever like a situationship. 😭

void est_node_set_timeout(ESTNODE *node, int sec);
  • node specifies a node connection object.
  • sec specifies the timeout of the connection in seconds.

est_node_set_auth

sets the authentication information of a node connection object. credentials era. 🔐

void est_node_set_auth(ESTNODE *node, const char *name, const char *passwd);
  • node specifies a node connection object.
  • name specifies the name of authentication.
  • passwd specifies the password of the authentication.

est_node_status

gets the status code of the last request of a node. receipts check. 🧐

int est_node_status(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is the status code of the last request of the node.
  • -1 means failure of connection. 💀

est_node_sync

synchronizes updating contents of the database of a node. sync up, bestie, it's giving "we need to talk". 🦋

int est_node_sync(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is true if success, else it is false.

est_node_optimize

optimizes the database of a node. glow-up for your database, literally. ✨

int est_node_optimize(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is true if success, else it is false.

est_node_put_doc

adds a document to a node. new doc, who dis. 📄

int est_node_put_doc(ESTNODE *node, ESTDOC *doc);
  • node specifies a node connection object.
  • doc specifies a document object. the document object should have the URI attribute.
  • the return value is true if success, else it is false.
  • if the URI attribute is same with an existing document in the node, the existing one is deleted. like, replaced. gone. bye. 💅

est_node_out_doc

removes a document from a node. we're breaking up with this doc. 😭

int est_node_out_doc(ESTNODE *node, int id);
  • node specifies a node connection object.
  • id specifies the ID number of a registered document.
  • the return value is true if success, else it is false.

est_node_out_doc_by_uri

removes a document specified by URI from a node. same energy, different lookup. 🔍

int est_node_out_doc_by_uri(ESTNODE *node, const char *uri);
  • node specifies a node connection object.
  • uri specifies the URI of a registered document.
  • the return value is true if success, else it is false.

est_node_edit_doc

edits attributes of a document in a node. not a full rewrite, just a lil edit. ✏️

int est_node_edit_doc(ESTNODE *node, ESTDOC *doc);
  • node specifies a node connection object.
  • doc specifies a document object.
  • the return value is true if success, else it is false.
  • the ID can not be changed. 🚫
  • if the URI is changed and it overlaps the URI of another registered document, this function fails. so watch out, that's a whole collision situation.

est_node_get_doc

retrieves a document in a node by ID. come here, doc. 🫴

ESTDOC *est_node_get_doc(ESTNODE *node, int id);
  • node specifies a node connection object.
  • id specifies the ID number of a registered document.
  • the return value is a document object. it should be deleted with est_doc_delete if it is no longer in use. don't ghost it.
  • on error, NULL is returned.

est_node_get_doc_by_uri

retrieves a document specified by URI in a node.

ESTDOC *est_node_get_doc_by_uri(ESTNODE *node, const char *uri);
  • node specifies a node connection object.
  • uri specifies the URI of a registered document.
  • the return value is a document object. it should be deleted with est_doc_delete if it is no longer in use.
  • on error, NULL is returned.

est_node_get_doc_attr

retrieves the value of an attribute of a document in a node. just one lil attribute. 🎀

char *est_node_get_doc_attr(ESTNODE *node, int id, const char *name);
  • node specifies a node connection object.
  • id specifies the ID number of a registered document.
  • name specifies the name of an attribute.
  • the return value is the value of the attribute, or NULL if it does not exist.
  • because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. you gotta free it, i'm not playing. 🚨

est_node_get_doc_attr_by_uri

retrieves the value of an attribute of a document specified by URI in a node.

char *est_node_get_doc_attr_by_uri(ESTNODE *node, const char *uri, const char *name);
  • node specifies a node connection object.
  • uri specifies the URI of a registered document.
  • name specifies the name of an attribute.
  • the return value is the value of the attribute, or NULL if it does not exist.
  • because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. same rule, same drama. 💜

est_node_etch_doc

extracts keywords of a document. keyword extraction, the scavenger hunt. 🔥

CBMAP *est_node_etch_doc(ESTNODE *node, int id);
  • node specifies a node connection object.
  • id specifies the ID number of a registered document.
  • the return value is a new map object of keywords and their scores in decimal string, or NULL on error.
  • because the object of the return value is opened with the function cbmapopen, it should be closed with the function cbmapclose if it is no longer in use. close the map, bestie, it's not a browser tab.

est_node_etch_doc_by_uri

extracts keywords of a document specified by URI in a node.

CBMAP *est_node_etch_doc_by_uri(ESTNODE *node, const char *uri);
  • node specifies a node connection object.
  • uri specifies the URI of a registered document.
  • the return value is a new map object of keywords and their scores in decimal string, or NULL on error.
  • because the object of the return value is opened with the function cbmapopen, it should be closed with the function cbmapclose if it is no longer in use.

est_node_uri_to_id

gets the ID of a document specified by URI. uri in, id out, a whole transformation. 🦋

int est_node_uri_to_id(ESTNODE *node, const char *uri);
  • node specifies a node connection object.
  • uri specifies the URI of a registered document.
  • the return value is the ID of the document.
  • on error, -1 is returned.

est_node_name

gets the name of a node. name check. 👑

const char *est_node_name(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is the name of the node.
  • on error, NULL is returned.
  • the life duration of the returned string is synchronous with the one of the node object. so like, don't free it, it belongs to the node. they're bonded fr fr. 🫶

est_node_label

gets the label of a node. cute lil label, we love a label. 🎀

const char *est_node_label(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is the label of the node.
  • on error, NULL is returned.
  • the life duration of the returned string is synchronous with the one of the node object. same deal as above.

est_node_doc_num

gets the number of documents in a node. headcount time. 🧮

int est_node_doc_num(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is the number of documents in the node.
  • on error, -1 is returned.

est_node_word_num

gets the number of unique words in a node. unique words only, we don't do repeats. 💅

int est_node_word_num(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is the number of unique words in the node.
  • on error, -1 is returned.

est_node_size

gets the size of the database of a node. how big is she. 📏

double est_node_size(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is the size of the database of the node.
  • on error, -1.0 is returned. (yes, double, yes, -1.0, not -1.) ✨

est_node_cache_usage

gets the usage ratio of the cache of a node. cache vibes, how full. 🌸

double est_node_cache_usage(ESTNODE *node);
  • node specifies a node connection object.
  • the return value is the usage ratio of the cache of the node.
  • on error, -1.0 is returned.

est_node_admins

gets a list of names of administrators of a node. the admin roll call, the group chat members list, iykyk. 👑

  • const CBLIST *est_node_admins(ESTNODE *node); — bestie, node is your node connection object, and you get back a list object stuffed with the names of the administrators. If it goes wrong? NULL, obviously. 😭 Heads up tho: the returned object lives exactly as long as the node object does — they're synchronized, no cap, so don't go deleting it behind anyone's back.

The function est_node_users is used in order to get a list of names of users of a node.

  • const CBLIST *est_node_users(ESTNODE *node); — node = node connection object. Return value = a list object of names of users ✨. On error, NULL is returned. Life duration of the returned object is synchronous with the one of the node object. Same deal as above, they're bonded fr.

The function est_node_links is used in order to get a list of expressions of links of a node.

  • const CBLIST *est_node_links(ESTNODE *node); — node = node connection object. Return value = a list object of expressions of links 🔗. Each element is a TSV string and has three fields: the URL, the label, and the score. On error, NULL is returned. Life duration of the returned object is synchronous with the one of the node object.

The function est_node_search is used in order to search a node for documents corresponding a condition.

  • ESTNODERES *est_node_search(ESTNODE *node, ESTCOND *cond, int depth); — node = node connection object, cond = condition object, and depth = the depth of meta search 🕵️. Return value is a node result object. Bestie, you must delete it with est_noderes_delete once you're done with it, okay? On error, NULL is returned.

The function est_node_set_snippet_width is used in order to set width of snippet in the result from a node.

  • void est_node_set_snippet_width(ESTNODE *node, int wwidth, int hwidth, int awidth); — node = node connection object. wwidth = whole width of a snippet. By default it's 480. If it's 0, no snippet is sent. If it's negative, the whole body text is sent instead of a snippet 😳. hwidth = width of strings picked up from the beginning of the text; by default 96. If it is negative 0, the current setting is not changed. awidth = width of strings picked up around each highlighted word; by default 96. If it is negative, the current setting is not changed.

The function est_node_set_user is used in order to manage a user account of a node.

  • int est_node_set_user(ESTNODE *node, const char *name, int mode); — node = node connection object, name = the name of a user, mode = the operation mode 👑. 0 means to delete the account, 1 means to set the account as an administrator, 2 means to set the account as a guest. Return value is true if success, else it is false.

The function est_node_set_link is used in order to manage a link of a node.

  • int est_node_set_link(ESTNODE *node, const char *url, const char *label, int credit); — node = node connection object, url = the URL of the target node of a link, label = the label of the link, and credit = the credit of the link 💅. If it is negative, the link is removed. Return value is true if success, else it is false.

✨ API FOR SEARCH RESULTS OF NODES ✨

The type of the structure ESTNODERES is for abstraction of search result from a node 🦋. A result is composed of a list of corresponding documents and information of hints. No entity of ESTNODERES is accessed directly, but it is accessed by the pointer. The term of node result object means the pointer and its referent. A node result object is created by the function est_node_search and destroyed by est_noderes_delete. Every created node connection object should be destroyed. Periodt.

The type of the structure ESTRESDOC is for abstraction of a document in search result 📄. A result document is composed of some attributes and a snippet. No entity of ESTRESDOC is accessed directly, but it is accessed by the pointer. The term of result document object means the pointer and its referent. A result document object is gotten by the function est_noderes_get_doc but it should not be destroyed because the entity is managed inside the node result object. Like, it's not yours to delete, bestie, hands off 🙈.

The function est_noderes_delete is used in order to delete a node result object.

  • void est_noderes_delete(ESTNODERES *nres); — nres = a node result object. Yeet it when you're done 🗑️.

The function est_noderes_hints is used in order to get a map object for hints of a node result object.

  • CBMAP *est_noderes_hints(ESTNODERES *nres); — nres = a node result object. Return value = a map object for hints. Keys of the map are "VERSION", "NODE", "HIT", "HINT#n", "DOCNUM", "WORDNUM", "TIME", "TIME#n", "LINK#n", and "VIEW". Life duration of the returned object is synchronous with the one of the node result object.

The function est_noderes_eclipse is used in order to eclipse similar documents of a node result object.

  • void est_noderes_eclipse(ESTNODERES *nres, int num, double limit); — nres = a node result object. num = the number of documents to be shown; if it is not more than 0, eclipse is undone. limit = the lower limit of similarity for documents to be eclipsed. Similarity is between 0.0 and 1.0 🌈.

The function est_noderes_doc_num is used in order to get the number of documents in a node result object.

  • int est_noderes_doc_num(ESTNODERES *nres); — nres = a node result object. Return value = the number of documents in a node result object 🔢.

The function est_noderes_get_doc is used in order to refer a result document object in a node result object.

  • ESTRESDOC *est_noderes_get_doc(ESTNODERES *nres, int index); — nres = a node result object, index = the index of a document. Return value = a result document object, or NULL if index is equal to or more than the number of documents. Life duration of the returned object is synchronous with the one of the node result object.

The function est_resdoc_uri is used in order to get the URI of a result document object.

  • const char *est_resdoc_uri(ESTRESDOC *rdoc); — rdoc = a result document object. Return value = the URI of the result document object 🔗. Life duration of the returned string is synchronous with the one of the result document object.

The function est_resdoc_attr_names is used in order to get a list of attribute names of a result document object.

  • CBLIST *est_resdoc_attr_names(ESTRESDOC *rdoc); — rdoc = a result document object. Return value = a new list object of attribute names of the result document object. And because the object of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use — close your loops, bestie, it's giving responsible 💅.

The function est_resdoc_attr is used in order to get the value of an attribute of a result document object.

  • const char *est_resdoc_attr(ESTRESDOC *rdoc, const char *name); — rdoc = a result document object, name = the name of an attribute. Return value = the value of the attribute, or NULL if it does not exist 🫥. Life duration of the returned string is synchronous with the one of the result document object.

The function est_resdoc_snippet is used in order to get the snippet of a result document object.

  • const char *est_resdoc_snippet(ESTRESDOC *rdoc); — rdoc = a result document object. Return value = a string of the snippet of the result document object ✨. There are tab separated values. Each line is a string to be shown. Though most lines have only one field, some lines have two fields. If the second field exists, the first field is to be shown with highlighted, and the second field means its normalized form. Life duration of the returned string is synchronous with the one of the result document object.

The function est_resdoc_keywords is used in order to get keywords of a result document object.

  • const char *est_resdoc_keywords(ESTRESDOC *rdoc); — rdoc = a result document object. Return value = a string of serialized keywords of the result document object 🔑. There are tab separated values. Keywords and their scores come alternately. Life duration of the returned string is synchronous with the one of the result document object.

The function est_resdoc_shadows is used in order to get an array of documents eclipsed by a result document object.

  • ESTRESDOC **est_resdoc_shadows(ESTRESDOC *rdoc, int *np); — rdoc = a result document object. np = the pointer to a variable to which the number of elements of the return value is assigned. Return value = an array of eclipsed result document objects 👻. Life duration of the returned array and its elements is synchronous with the one of the result document object.

The function est_resdoc_similarity is used in order to get similarity of an eclipsed result document object.

  • double est_resdoc_similarity(ESTRESDOC *rdoc); — rdoc = a result document object. Return value = similarity of the result document object to the front document, or -1.0 if it is not eclipsed 📏.

🌈 PARALLELING 🌈

Okay so listen up, this one matters 🔥. Each of node connection objects, node result objects, and result document objects can not be shared by threads. Nope. Not happening. If you use multi threads, make each thread have its own objects, bestie, everyone gets their own 🫶. If the precondition is kept, functions of the node API can be treated as thread-safe functions. Slay.

👑 AUTHOR 👑

Hyper Estraier is written by Mikio Hirabayashi 💖. You can contact the author by e-mail to <mikio@users.sourceforge.net>. Any suggestion or bug report is welcome to the author. Fr fr, they want to hear from you.

🎀 ACKNOWLEDGEMENTS 🎀

Hyper Estraier was developed under management by Fumitoshi Ukai and supports by Exploratory Software Project of Information-technology Promotion Agency, Japan (IPA) 🌸. Iconic.

okay so legal era, bestie — gotta give credit where credit is due 💖

Copyright (C) 2004-2007 Mikio Hirabayashi

Hyper Estraier is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.

Hyper Estraier is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

no cap, that warranty disclaimer is doing the most for a reason — it literally means there's no warranty. read the license, bestie.

You should have received a copy of the GNU Lesser General Public License along with Hyper Estraier; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

🌈 SEE ALSO 🌈

the whole friend group, assembled 🫶 go say hi:

Please see http://hyperestraier.sourceforge.net/nguide-en.html for detail.

and that's the whole page, bestie!! you made it all the way to the end, main character energy fr fr 💅✨

this gorgeous lil page is ESTNODE(3) from 2007-03-06, and the header up top literally just says Man Page — so that's the source/version vibe it's rockin'. 🦋

go build something iconic with it. obsessed with you. mwah. 💖🌸

📦 where this page comes from