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().
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 and automatically for your convenience, then repopulated with the next received instruction (if available).
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 and automatically for your convenience, then repopulated with the next received instruction.
- opcode is the instruction code to wait for.
This function should only be used in circumstances where you have sent the server a request with a guaranteed response, and have not called hipe_next_instruction() since then. Otherwise your application may hang waiting for an instruction that may never arrive (or worse, might have already arrived but been buffered in the received-instructions queue by hipe_next_instruction(), which is not checked by hipe_await_instruction()).
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).
- 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 value that was assigned to the most recently created tag. This function is more efficient than sending instructions to the server to obtain location details.