Subversion Repositories Kolibri OS

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
895 barsuk 1 
Global clipboard for Kolibri. Notes for developers.
2 
 
3 
General info
4 
Clipboard is implemented using daemon process and IPC messages.
5 
To test, run @clip (the daemon process) and cliptest and debug board
6 
or test2 (several instances).
7 
 
8 
1. @clip daemon and its commands
9 
 
10 
Process @clip creates no windows, but only listens for IPC messages.
11 
Daemon supports 16 (MAX_FORMAT) buffers for different data types and up to
12 
16,7 Mb (MAX_SIZE) data in each buffer (memory is allocated from heap).
13 
Data format ID is a number from 0 to 65534. Value 65535 is reserved.
14 
 
15 
When the daemon is started it terminates all other @clip instances.
16 
Format of daemon's commands is following:
17 
 
18 
[ Cmd: word | Format: word | Reserved: Dword | Data: ...]
19 
 
20 
where Cmd is command id,
21 
Format is data format id,
22 
Reserved is unused (should be zero),
23 
and Data is command-specific data.
24 
 
25 
Following commands are implemented:
26 
 
27 
1. Set Size. Define required size for buffer. This command causes daemon to
28 
enlarge (if needed) its IPC buffer (there is currently no way to decrease
29 
size of the buffer).
30 
Data parameter: Dword with size of the data.
31 
Command length: 12 bytes.
32 
 
33 
2. Set. Data transfer. This command copies data to daemon's memory.
34 
Data parameter: data to be copied.
35 
Command length: 8 + (data size) bytes.
36 
 
37 
3. Get Size. Get size of data with specified format id. This command causes
38 
daemon to send in reply an IPC message telling the size of the data in the buffer.
39 
If the buffer contains no data, 0 is returned.
40 
Command length: 8 bytes.
41 
 
42 
4. Get. Get the data with specified format id from the buffer. This command
43 
causes daemon to send in reply an IPC message of required size with the data
44 
from the buffer. If the buffer contains no data, no message is sent.
45 
Command length: 8 bytes.
46 
 
47 
5. Delete. Clear the buffer for specified format id. If 0xFFFF is specified,
48 
all buffers are cleared.
49 
Command length: 8 bytes.
50 
 
51 
Source: @clip.asm. Uncomment the line:
52 
;define DEBUG TRUE
53 
and comment the next one to enable output on debug board. This is useful
54 
for bugtracking.
55 
DEFAULT_SIZE is initial IPC buffer size
56 
MAX_SIZE is upper limit of IPC buffer size
57 
MAX_FORMAT is number of formats daemon can store as the same time
58 
(if more formats are copied, daemon will crash).
59 
DELAY is pause between sending attepmts, 1/100 seconds.
60 
ATTEMPT is number of sending attempts if target process is not ready.
61 
 
62 
 
63 
2. clip.inc: function set for high-level communication with @clip.
64 
Reading and writing is implemeted.
65 
 
66 
Usage example: cliptest.asm (writes to debug board) and test2.asm.
67 
 
68 
Following values should be defined:
69 
DEFAULT_MASK = 7	; Default event mask for current thread
70 
 
71 
SEND_DELAY = 10		; pause between sending attempts
72 
 
73 
RECV_DELAY = 100	; how much to wait for the answer
74 
			; 1/100 secs
75 
 
76 
ATTEMPT = 5		; number of sending attempts
77 
 
78 
Clip.inc contains the following functions:
79 
 
80 
clipboard_init() - search of process @clip. May be called several times.
81 
Returns 1 if successful and 0 if failed.
82 
 
83 
clipboard_write(esi points to CLIP_BUFFER,
84 
ax (word) - data format id) - copies data to buffer.
85 
Uses 1-th and 2-nd commands.
86 
Returns 1 if successful and 0 if failed.
87 
 
88 
clipboard_read(esi points to CLIP_BUFFER,
89 
ax (word) - data format id) - retrieves data from buffer.
90 
Uses 3-rd and 4-th commands.
91 
Returns 1 if successful, -1 if not enough data in receive buffer (which is
92 
left unchanged in this case) and 0 if failed.
93 
If eax = 1 or -1, edx contains real size of data in the buffer.
94 
 
95 
Warning. If the application uses incoming IPC messages for other
96 
purposes, process daemon's messages manually, because getting a different
97 
format message will be ignored by clipboard_read.
98 
 
99 
There are 2 low-level functions which may be called after clipboard_init:
100 
_ipc_send (esi points to a common buffer, edx - byte count).
101 
Sends an IPC message to daemon. The difference between this function and
102 
function 60/2 is that _ipc_send makes several attempts if daemon is
103 
unaccessible, with pause of SEND_DELAY/100 seconds.
104 
Returns 1 if successful and 0 if failed.
105 
 
106 
_ipc_recv(esi points to CLIP_BUFFER (см. далее),
107 
edx = default event mask).
108 
Waits for an IPC message for RECV_DELAY/100 seconds.
109 
If successful, result is stored in esi.
110 
Returns 1 if successful and 0 if failed.
111 
 
112 
Format of buffer for clipboard:
113 
CLIP_BUFFER
114 
(+0)	.size	dd	?	; size of the buffer itself(N)
115 
				; if you need to send less bytes that N
116 
				; temporarily write the required size here
117 
 
118 
(+4)	.sys1	dd	?	; \  clip.inc uses these fields
119 
				;  - for internal values. You should not
120 
(+8)	.sys2	dd	?       ; /  modify them
121 
 
122 
(+12)	.data	db	N dup(?); buffer itself
123 
 
124 
Good luck in programming and debugging!
125 
 
126 
; barsuk, 21.08.2008
127 
 
128 
 
129 
 
130 
 
131 
@CLIP version 0.2.
132 
 
133 
A capability of inserting text to applications not using @clip is added.
134 
Function 72/1 is used to insert the text.
135 
Only applications, using ascii mode for input are supported.
136 
 
137 
To insert text press ctrl-alt-v hot key.
138 
The text should be copied to 1-st buffer from @clip-compatible
139 
application (example: test2).
140 
 
141 
; 08.09.2008