xpaget(3)

✨ XPAGet — bestie edition ✨

okay so this is xpaget(3), a page from the SAORD Documentation collection 💖 it's the C function you call when you want to go grab data from one or more XPA servers. strap in, it's lowkey iconic.

---

🌸 NAME 🌸

XPAGet — retrieve data from one or more XPA servers. yes literally just that. it's giving "getter but make it networked" 💅

---

🎀 SYNOPSIS 🎀

#include <xpa.h>

int XPAGet(XPA xpa,
           char *template, char *paramlist, char *mode,
           char **bufs, size_t *lens, char **names, char **messages,
           int n);

---

🦋 DESCRIPTION 🦋

so basically you want data from one or more XPA servers whose class:name identifier matches the template you give it. that's the whole vibe. 🫶

You hand over a template shaped like "class1:name1", and it gets sent off to the XPA name server, which hands you back a list of at most n matching XPA servers. no cap. Then a connection gets established with each of those servers, and the paramlist string gets passed along to the server right as the data transfer request kicks off.

Now here's a little fork in the road 👀 if you pass an XPA struct into the call, then the persistent connections get updated as described above. If you don't, then it just makes temporary connections to the servers instead — and those get closed the moment the call completes. bye girl 💨

Then XPAGet() does its thing: it retrieves data from at most n XPA servers, drops those data into n allocated buffers, and puts the buffer pointers into the bufs array. the length of each buffer lands in the lens array. a string containing the class:name and ip:port goes into the name array. (yes, "name" singular in the prose, "names" in the signature, we don't make the rules 💀)

If a given server returned an error, or the server callback sends a message back to the client, then that message gets stored in the associated element of the messages array.

NB: if specified, the name and messages arrays must be of size n or greater. do not play with this. 🙈

The returned message string will be of the form:

XPA$ERROR error-message (class:name ip:port)

or

XPA$MESSAGE message (class:name ip:port)

heads up bestie: when there's an error stored in a messages entry, the corresponding bufs and lens entry may or may not be NULL and 0 (respectively) — it fully depends on the particularities of the server. so don't assume, okay? 😭

The return value will contain the actual number of servers that were processed. so this value holds the number of valid entries in the bufs, lens, names, and messages arrays, and you can use it to loop through those arrays. if names and/or messages is NULL, no information gets passed back in that array. simple as. ✨

The bufs, names, and messages arrays should be freed upon completion (if they are not NULL). memory hygiene is self care, fr fr 🧚

The mode string is shaped like: "key1=value1,key2=value2,..."

The following keywords are recognized:

• ack — value: true/false, default: true. if false, don't wait for ack from server (after callback completes).
• doxpa — value: true/false, default: true. client processes xpa requests.

The ack keyword is not very useful, since the server completes the callback in order to return the data anyway. it's here for completion (and perhaps for future usefulness). honestly? filler. but we keep it 💅

Normally, an XPA client will process incoming XPA server requests while awaiting the completion of the client request. Setting this variable to "false" will prevent XPA server requests from being processed by the client.

Example:

#include <xpa.h>

#define NXPA 10
int  i, got;
size_t  lens[NXPA];
char *bufs[NXPA];
char *names[NXPA];
char *messages[NXPA];
got = XPAGet(NULL, "ds9", "file", NULL, bufs, lens, names, messages,
NXPA);
for(i=0; i<got; i++){
  if( messages[i] == NULL ){
    /* process buf contents */
    ProcessImage(bufs[i], ...);
    free(bufs[i]);
  }
  else{
    /* error processing */
    fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]);
  }
  if( names[i] )
    free(names[i]);
  if( messages[i] )
    free(messages[i]);
}

---

💜 SEE ALSO 💜

See xpa(n) for a list of XPA help pages 🌈

---

that's the whole page bestie, go forth and XPAGet responsibly 👑

this was version 2.1.15, dated July 23, 2013 — yeah it's a vintage, and it still ate. periodt. 💖✨🎀