Hipe : The DOM on the desktop
How Hipe Works  |  Installation  |  Running hiped  |  Hipe API

The Hipe API
Including libhipe
libhipe functions
C++ extensions
Multithreading considerations
Hipe instructions
Interprocess communication
HIPE_OP_ADD_FONT
HIPE_OP_ADD_STYLE_RULE
HIPE_OP_ADD_STYLE_RULE_SRC
HIPE_OP_APPEND_TAG
HIPE_OP_APPEND_TEXT
HIPE_OP_ATTRIBUTE_RETURN
HIPE_OP_AUDIOVIDEO_STATE
HIPE_OP_CANVAS_ACTION
HIPE_OP_CANVAS_SET_PROPERTY
HIPE_OP_CARAT_POSITION
HIPE_OP_CLEAR
HIPE_OP_EDIT_ACTION
HIPE_OP_CONTAINER_GRANT
HIPE_OP_CONTENT_RETURN
HIPE_OP_DELETE
HIPE_OP_DIALOG
HIPE_OP_DIALOG_INPUT
HIPE_OP_DIALOG_RETURN
HIPE_OP_EVENT
HIPE_OP_EVENT_CANCEL
HIPE_OP_EVENT_REQUEST
HIPE_OP_FIFO_ADD_ABILITY
HIPE_OP_FIFO_CLOSE
HIPE_OP_FIFO_DROP_PEER
HIPE_OP_FIFO_GET_PEER
HIPE_OP_FIFO_OPEN
HIPE_OP_FIFO_REMOVE_ABILITY
HIPE_OP_FIFO_RESPONSE
HIPE_OP_FILE_RETURN
HIPE_OP_FIND_TEXT
HIPE_OP_FRAME_CLOSE
HIPE_OP_FRAME_EVENT
HIPE_OP_FREE_LOCATION
HIPE_OP_GEOMETRY_RETURN
HIPE_OP_GET_ATTRIBUTE
HIPE_OP_GET_AUDIOVIDEO_STATE
HIPE_OP_GET_BY_ID
HIPE_OP_GET_CARAT_POSITION
HIPE_OP_GET_CONTENT
HIPE_OP_GET_FIRST_CHILD
HIPE_OP_GET_FRAME_KEY
HIPE_OP_GET_GEOMETRY
HIPE_OP_GET_LAST_CHILD
HIPE_OP_GET_NEXT_SIBLING
HIPE_OP_GET_PREV_SIBLING
HIPE_OP_GET_SCROLL_GEOMETRY
HIPE_OP_GET_SELECTION
HIPE_OP_KEY_RETURN
HIPE_OP_LOCATION_RETURN
HIPE_OP_MESSAGE
HIPE_OP_OPEN_LINK
HIPE_OP_REMOVE_ATTRIBUTE
HIPE_OP_REQUEST_CONTAINER
HIPE_OP_SCROLL_BY
HIPE_OP_SCROLL_TO
HIPE_OP_SERVER_DENIED
HIPE_OP_SET_ATTRIBUTE
HIPE_OP_SET_FOCUS
HIPE_OP_SET_ICON
HIPE_OP_SET_SRC
HIPE_OP_SET_STYLE
HIPE_OP_SET_STYLE_SRC
HIPE_OP_SET_TEXT
HIPE_OP_SET_TITLE
HIPE_OP_TAKE_SNAPSHOT
HIPE_OP_TOGGLE_CLASS
HIPE_OP_USE_CANVAS

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.

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.

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);

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.

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.

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).

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.