Hipe instructions
Anatomy of an instruction
The hipe_instruction data type produces a C struct with the following member variables:
char opcode, /* 8 bits */ uint64_t requestor, /* 64 bits */ hipe_loc location, /* 64 bits */ uint64_t arg_length[4],/* 64 bits per length value */ char* arg[4] /* size of each element as specified in arg_length[] */
opcode identifies the nature of the instruction request. You should fill this field using only the predefined macro constants provided by the Hipe API, which are all prefixed by HIPE_OP_ (the prefix was HIPE_OPCODE_ in older versions).
requestor is a 64-bit unsigned integer which you can use to identify an instruction request in a meaningful way. When the Hipe server receives an instruction from an application that requires a response, it passes back the same requestor value in the response. The value of requestor is not interpreted by Hipe in any way. You can use requestor in any number of ways. For example, when requesting events from a calculator utility, you might request that when the user clicks numerical buttons, the events are identified with a requestor value equal to the numerical value of the button clicked. In a more general case, for example when developing a complete GUI toolkit, you might pass as requestor a pointer to an object that will handle a particular event, or deal with a particular subset of incoming instructions.
location is a 64-bit unsigned integer which serves as a numerical handle corresponding to a particular element in the Document Object Model (i.e. a particular HTML tag). Location 0 refers to the <body> element which encloses all other elements within the application frame.
arg[] elements are character strings carrying a different meaning depending on the opcode of the instruction being passed.
arg_length[] specifies the corresponding length of each arg[] element, excluding any null-termination character at the end of the argument string. (Hipe does not expect arguments to be null-terminated.)
If an argument is unused (or not required in a particular instruction), its corresponding arg_length[] element should be assigned a value of 0, and the arg[] element itself may be assigned a NULL pointer.
Transmission of an instruction
The first 49 bytes of a transmitted Hipe instruction form the 'instruction preamble.' The preamble specifies the opcode, requestor and location (the subject of the instruction), as well as the remaining instruction length. Any arguments are then concatenated to the preamble. The arguments may be of any length (or no length at all, depending on the instruction). The recipient therefore reads the preamble first in order to know how much memory to allocate to storing the rest of the instruction. An instruction must be entirely received at the other end before it can be used.