libhipe functions

Functions for creating and destroying a Hipe frame

Each application is granted a single frame when it connects to Hipe. A frame is a rectangular window on the screen through which that application is able to interact with the user. Applications are not normally allowed to create multiple frames, although they can create their own sub-frames for embedding other applications inside.

hipe_open_session()

This function connects to the Hipe display server and requests a frame.

hipe_session hipe_open_session(const char* host_key, const char* socket_path,
                               const char* key_path, const char* client_name)

Returns a value of type hipe_session on success. The return value is a session handle which is required by other hipe functions. On failure, the function returns 0, and an error message is printed to stderr.

• host_key (optional) is a unique key-string that may be supplied by a particular Hipe environment (such as a framing manager). In most cases, you should pass 0 (a null value, not the string "0") and let libhipe obtain the key automatically from environment variables and hostkey files.
• socket_path (optional) is the location of the Hipe display server socket file. In most cases you should pass 0 and let libhipe deduce the socket path automatically from environment variables and fallback paths.
• key_path (optional) is the location of a file containing a valid host-key for connection to a Hipe environment. In most cases you should pass 0 and let libhipe deduce this information automatically from environment variables and fallback paths.
• client_name is a short name that identifies the application process. It is quite reasonable to use argv[0] here. This short name also serves as a temporary title placeholder until you set the frame title properly.

hipe_close_session()

This function disconnects from the Hipe server and closes the session. The application's frame is destroyed and server resources associated with it are freed.

short hipe_close_session(hipe_session session)

Returns 0 on success.

• session is the session handle that was obtained when hipe_open_session() was called. After calling hipe_close_session(), the session handle is no longer valid and should not be used again.

Functions for dealing with Hipe instruction structures

libhipe uses data structures of type hipe_instruction for sending and receiving instructions from the display server. The functions for managing these variables all start with the prefix hipe_instruction_.

hipe_instruction_init()

Initialises a hipe_instruction instance by making its internal pointers null, making it safe for use in Hipe API functions.

void hipe_instruction_init(hipe_instruction* obj)

Must be called on any new hipe_instruction instance (excluding shallow copies of an existing instance).

Must also be called on a hipe_instruction object whose values have been populated manually by the user (e.g. by assigning as arguments string pointers that are not owned by the hipe_instruction object itself) and is now going to be re-used by a Hipe API function.

hipe_instruction_clear()

Frees memory allocated within the instruction, and leaves the hipe_instruction structure in a clean state ready for reuse.

void hipe_instruction_clear(hipe_instruction* obj)

Do not use this function to clear a hipe_instruction for which you have allocated values yourself. Instead, de-allocate the argument strings in a way consistent with how you allocated them, then call hipe_instruction_init() to re-initialise the values into a clean state.

hipe_instruction_copy()

Deeply copies values from one hipe_instruction instance to another, allocating memory for storage of values in the destination instance.

void hipe_instruction_copy(hipe_instruction* dest, hipe_instruction* src);

• dest is the hipe_instruction instance into which values will be be copied. dest should be in a clean state, as hipe_instruction_copy() does not do any initialisation or de-allocation of any existing data in dest.
• src is the hipe_instruction instance values are to be copied from.

When done with the instruction values in dest, you should free the memory associated with its internal variables using hipe_instruction_clear().

hipe_instruction_alloc()

Allocates memory for each argument of an instruction, according to the lengths already set in its arg_length[] values. Use it when building an instruction by hand whose arguments you will then fill in.

void hipe_instruction_alloc(hipe_instruction* obj)

Arguments allocated in this way should later be freed with hipe_instruction_clear().

hipe_instruction_move()

Moves the contents of one hipe_instruction instance into another without copying the arguments: the memory belonging to src is handed over to dest, and src is left re-initialised.

void hipe_instruction_move(hipe_instruction* dest, hipe_instruction* src);

As with hipe_instruction_copy(), dest should be in a clean state beforehand. The memory now in dest should later be freed in the way that suits how src was filled: with hipe_instruction_clear() if libhipe allocated it.

Functions for sending and receiving Hipe instructions

All interaction with the Hipe display server is done by sending and receiving Hipe instructions.

hipe_next_instruction()

Gets the next instruction from the display server, with an optional blocking wait.

short hipe_next_instruction(hipe_session session, hipe_instruction* instruction_ret,
                            short blocking)

Returns 1 if an instruction has been received, 0 if no instruction is available at the present moment and blocking was not requested, or -1 if disconnection from the server has occurred.

• session is the session handle that was obtained when hipe_open_session() was called.
• The received instruction is copied into *instruction_ret. The passed instruction variable must have been correctly initialised at the time it was created (using hipe_instruction_init()) but does not need to have been cleared before calling this function. It will be cleared automatically for your convenience, then repopulated with the next received instruction (if available).

Always check for a return value of -1 (or an instruction_ret->opcode of HIPE_OP_SERVER_DENIED) in your event loop, and exit (or otherwise stop calling hipe_next_instruction()) when it occurs. Once a session is disconnected, a blocking call can no longer block on anything, so an application that keeps calling hipe_next_instruction() in a tight loop without checking for disconnection will spin continuously instead of exiting cleanly when the display server goes away.

hipe_await_instruction()

A variation of the hipe_next_instruction function that waits for a specific type of instruction. There is a blocking wait until an instruction with the specified opcode arrives. When this happens, that instruction will jump the queue and be returned first.

short hipe_await_instruction(hipe_session session, hipe_instruction* instruction_ret,
                             short opcode)

Returns 1 if an instruction of type opcode has been received or -1 if disconnection from the server has occurred.

• session is the session handle that was obtained when hipe_open_session() was called.
• The received instruction is copied into *instruction_ret. instruction_ret must have been correctly initialised but does not need to have been cleared before calling this function. It will be cleared automatically for your convenience, then repopulated with the next received instruction.
• opcode is the instruction code to wait for.

Instructions that have already been received and are waiting in the queue are checked first, oldest first, so a reply that arrived while you were awaiting something else is still found. Any other instructions that arrive during the wait are added to the queue, to be retrieved later with hipe_next_instruction().

This function should only be used when you have sent the server a request that is guaranteed a response. Otherwise your application will hang waiting for an instruction that never arrives. That includes the case where the response has already been taken out of the queue by a call to hipe_next_instruction(): once retrieved, it is no longer there to be found.

hipe_session_fd()

Returns the file descriptor of the session's connection to the display server, so that an application can wait for Hipe instructions and its own file descriptors (pipes, FIFOs, sockets) at the same time, using poll(), select() or epoll, instead of checking each one on a timer.

int hipe_session_fd(hipe_session session)

Returns the file descriptor, or -1 if there is no connection to the display server.

• session is the session handle that was obtained when hipe_open_session() was called.

Only wait on this file descriptor for readability. Never read from or write to it directly: use hipe_next_instruction() and the send functions.

Important: libhipe keeps a queue of instructions it has already received. A single read can take in several instructions, and hipe_await_instruction() queues every instruction that isn't the one it's waiting for. Queued instructions are no longer waiting in the connection, so they won't wake poll(). Always empty the queue with non-blocking calls to hipe_next_instruction() before waiting:

for(;;) {
    while(hipe_next_instruction(session, &instruction, 0) > 0)
        handle(&instruction);
    poll(fds, nfds, -1);  /* fds includes hipe_session_fd(session) */
    /* ...handle your own file descriptors... */
}

A readable file descriptor doesn't guarantee that a complete instruction has arrived, so hipe_next_instruction() may still return 0. In that case, just wait again.

hipe_queued_instructions()

Returns the number of instructions that libhipe has received and queued, but that haven't yet been retrieved with hipe_next_instruction().

int hipe_queued_instructions(hipe_session session)

• session is the session handle that was obtained when hipe_open_session() was called.

This function doesn't read from the connection, so it doesn't count data the server has sent that hasn't been read yet. It's mainly useful for checking that the queue is empty before waiting on hipe_session_fd(). Like hipe_next_instruction(), it first sends any instructions waiting in the send buffer (see hipe_set_buffered()).

hipe_set_buffered()

Turns send buffering on or off for a session. Buffering is off by default, and each instruction is transmitted as soon as it is sent. With buffering on, sent instructions are collected and transmitted together, which is much more efficient for an application that sends many instructions at once (for example, building a large document or table). The order of instructions is always preserved.

void hipe_set_buffered(hipe_session session, int buffered)

• session is the session handle that was obtained when hipe_open_session() was called.
• buffered is non-zero to turn buffering on, or 0 to turn it off (which also transmits anything waiting).

Buffered instructions are transmitted when the buffer fills up (at 64 KiB), when the application waits or checks for instructions from the display server (with hipe_next_instruction(), hipe_await_instruction() or hipe_queued_instructions()), when hipe_flush() is called, when buffering is turned off, and when the session is closed. So a request is always transmitted before the application waits for its reply, and an application that drains hipe_next_instruction() before waiting on hipe_session_fd() (as described above) never needs to flush.

An application that sends instructions and then waits for something else without calling any of those functions (a timer, or one of its own file descriptors) must call hipe_flush() first. Otherwise its last instructions stay in the buffer, and the screen isn't updated, until it next does.

hipe_flush()

Transmits any instructions waiting in the session's send buffer.

int hipe_flush(hipe_session session)

Returns 0 on success, or -1 if there is no connection to the display server (or the connection has failed). It does nothing if buffering is off or nothing is waiting.

• session is the session handle that was obtained when hipe_open_session() was called.

hipe_send_instruction()

Transmits an instruction to the display server.

int hipe_send_instruction(hipe_session session, hipe_instruction instruction)

Returns 0 on success or -1 if there is no connection to the display server (or the connection has failed). With send buffering on (see hipe_set_buffered()), the instruction may be held in the buffer and transmitted later.

• session is the session handle that was obtained when hipe_open_session() was called.
• instruction is the Hipe instruction to transmit to the display server.

hipe_send()

A convenience function for transmitting a simple instruction to the display server without having to create a hipe_instruction instance first.

int hipe_send(hipe_session session, char opcode, uint64_t requestor, hipe_loc location,
              int n_args[, const char* arg, ...])

This function calls hipe_send_instruction internally and returns the return value from that call.

• session is the session handle that was obtained when hipe_open_session() was called.
• opcode, requestor, location and arg, ... are parts of the Hipe instruction to transmit. The strings arg[] need to be null-terminated, and their lengths are determined automatically. This convenience function should only be used when the arguments are simple text strings (due to the null-termination requirement).
• nargs is the number of arguments specified in the function call. Zero or more arguments may be specified at the end of the argument list.
• If an argument is explicitly specified but not used at a particular position, pass 0 (a null pointer) instead of a blank string.

hipe_newest_location()

Retrieves the location value of the most recently created tag.

hipe_loc hipe_newest_location()

Returns the location that was given to the tag created by this thread's most recent HIPE_OP_APPEND_TAG or HIPE_OP_INSERT_TAG, in whichever session. Read it straight after sending. Reserving locations doesn't change it. See "Locations".

hipe_reserve_location(), hipe_reserve_locations()

Reserve location numbers for elements you will create with markup (hipe-loc="N", text mode 3). Nothing is sent to the display server.

hipe_loc hipe_reserve_location(hipe_session session)
hipe_loc hipe_reserve_locations(hipe_session session, size_t count)

hipe_reserve_locations() reserves count consecutive numbers and returns the first. A reserved number you don't use must be freed with HIPE_OP_FREE_LOCATION, like any other.

hipe_send_markup()

Sends markup (text mode 3) together with the list of locations it uses.

int hipe_send_markup(hipe_session session, hipe_loc where, const char* markup, int append,
                     const hipe_loc* reserved, size_t count)

Replaces the contents of where (append == 0, HIPE_OP_SET_TEXT) or appends to them (HIPE_OP_APPEND_TEXT). reserved lists the count numbers used in the markup's hipe-loc attributes; consecutive numbers are sent as ranges. Returns as hipe_send().

hipe_last_error()

const char* hipe_last_error(hipe_session session)

The display server's reason for disconnecting session (for example "location 57 already in use"), or "". With session == 0: the reason the last hipe_open_session() was refused, or "". Lets an application tell its user why it lost its frame.