forked from KolibriOS/kolibrios
141 lines
5.0 KiB
Plaintext
141 lines
5.0 KiB
Plaintext
Global clipboard for Kolibri. Notes for developers.
|
||
|
||
General info
|
||
Clipboard is implemented using daemon process and IPC messages.
|
||
To test, run @clip (the daemon process) and cliptest and debug board
|
||
or test2 (several instances).
|
||
|
||
1. @clip daemon and its commands
|
||
|
||
Process @clip creates no windows, but only listens for IPC messages.
|
||
Daemon supports 16 (MAX_FORMAT) buffers for different data types and up to
|
||
16,7 Mb (MAX_SIZE) data in each buffer (memory is allocated from heap).
|
||
Data format ID is a number from 0 to 65534. Value 65535 is reserved.
|
||
|
||
When the daemon is started it terminates all other @clip instances.
|
||
Format of daemon's commands is following:
|
||
|
||
[ Cmd: word | Format: word | Reserved: Dword | Data: ...]
|
||
|
||
where Cmd is command id,
|
||
Format is data format id,
|
||
Reserved is unused (should be zero),
|
||
and Data is command-specific data.
|
||
|
||
Following commands are implemented:
|
||
|
||
1. Set Size. Define required size for buffer. This command causes daemon to
|
||
enlarge (if needed) its IPC buffer (there is currently no way to decrease
|
||
size of the buffer).
|
||
Data parameter: Dword with size of the data.
|
||
Command length: 12 bytes.
|
||
|
||
2. Set. Data transfer. This command copies data to daemon's memory.
|
||
Data parameter: data to be copied.
|
||
Command length: 8 + (data size) bytes.
|
||
|
||
3. Get Size. Get size of data with specified format id. This command causes
|
||
daemon to send in reply an IPC message telling the size of the data in the buffer.
|
||
If the buffer contains no data, 0 is returned.
|
||
Command length: 8 bytes.
|
||
|
||
4. Get. Get the data with specified format id from the buffer. This command
|
||
causes daemon to send in reply an IPC message of required size with the data
|
||
from the buffer. If the buffer contains no data, no message is sent.
|
||
Command length: 8 bytes.
|
||
|
||
5. Delete. Clear the buffer for specified format id. If 0xFFFF is specified,
|
||
all buffers are cleared.
|
||
Command length: 8 bytes.
|
||
|
||
Source: @clip.asm. Uncomment the line:
|
||
;define DEBUG TRUE
|
||
and comment the next one to enable output on debug board. This is useful
|
||
for bugtracking.
|
||
DEFAULT_SIZE is initial IPC buffer size
|
||
MAX_SIZE is upper limit of IPC buffer size
|
||
MAX_FORMAT is number of formats daemon can store as the same time
|
||
(if more formats are copied, daemon will crash).
|
||
DELAY is pause between sending attepmts, 1/100 seconds.
|
||
ATTEMPT is number of sending attempts if target process is not ready.
|
||
|
||
|
||
2. clip.inc: function set for high-level communication with @clip.
|
||
Reading and writing is implemeted.
|
||
|
||
Usage example: cliptest.asm (writes to debug board) and test2.asm.
|
||
|
||
Following values should be defined:
|
||
DEFAULT_MASK = 7 ; Default event mask for current thread
|
||
|
||
SEND_DELAY = 10 ; pause between sending attempts
|
||
|
||
RECV_DELAY = 100 ; how much to wait for the answer
|
||
; 1/100 secs
|
||
|
||
ATTEMPT = 5 ; number of sending attempts
|
||
|
||
Clip.inc contains the following functions:
|
||
|
||
clipboard_init() - search of process @clip. May be called several times.
|
||
Returns 1 if successful and 0 if failed.
|
||
|
||
clipboard_write(esi points to CLIP_BUFFER,
|
||
ax (word) - data format id) - copies data to buffer.
|
||
Uses 1-th and 2-nd commands.
|
||
Returns 1 if successful and 0 if failed.
|
||
|
||
clipboard_read(esi points to CLIP_BUFFER,
|
||
ax (word) - data format id) - retrieves data from buffer.
|
||
Uses 3-rd and 4-th commands.
|
||
Returns 1 if successful, -1 if not enough data in receive buffer (which is
|
||
left unchanged in this case) and 0 if failed.
|
||
If eax = 1 or -1, edx contains real size of data in the buffer.
|
||
|
||
Warning. If the application uses incoming IPC messages for other
|
||
purposes, process daemon's messages manually, because getting a different
|
||
format message will be ignored by clipboard_read.
|
||
|
||
There are 2 low-level functions which may be called after clipboard_init:
|
||
_ipc_send (esi points to a common buffer, edx - byte count).
|
||
Sends an IPC message to daemon. The difference between this function and
|
||
function 60/2 is that _ipc_send makes several attempts if daemon is
|
||
unaccessible, with pause of SEND_DELAY/100 seconds.
|
||
Returns 1 if successful and 0 if failed.
|
||
|
||
_ipc_recv(esi points to CLIP_BUFFER (<28><>. <20><><EFBFBD><EFBFBD><EFBFBD>),
|
||
edx = default event mask).
|
||
Waits for an IPC message for RECV_DELAY/100 seconds.
|
||
If successful, result is stored in esi.
|
||
Returns 1 if successful and 0 if failed.
|
||
|
||
Format of buffer for clipboard:
|
||
CLIP_BUFFER
|
||
(+0) .size dd ? ; size of the buffer itself(N)
|
||
; if you need to send less bytes that N
|
||
; temporarily write the required size here
|
||
|
||
(+4) .sys1 dd ? ; \ clip.inc uses these fields
|
||
; - for internal values. You should not
|
||
(+8) .sys2 dd ? ; / modify them
|
||
|
||
(+12) .data db N dup(?); buffer itself
|
||
|
||
Good luck in programming and debugging!
|
||
|
||
; barsuk, 21.08.2008
|
||
|
||
|
||
|
||
|
||
@CLIP version 0.2.
|
||
|
||
A capability of inserting text to applications not using @clip is added.
|
||
Function 72/1 is used to insert the text.
|
||
Only applications, using ascii mode for input are supported.
|
||
|
||
To insert text press ctrl-alt-v hot key.
|
||
The text should be copied to 1-st buffer from @clip-compatible
|
||
application (example: test2).
|
||
|
||
; 08.09.2008 |