Mercurial > vim

comparison runtime/doc/channel.txt @ 7935:3f2e0b62003d v7.4.1263

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commit https://github.com/vim/vim/commit/4d919d748e4e435edb135aa5ccf6ee7de9212023 Author: Bram Moolenaar <Bram@vim.org> Date: Fri Feb 5 22:36:41 2016 +0100 patch 7.4.1263 Problem: ch_open() hangs when the server isn't running. Solution: Add a timeout. Use a dict to pass arguments. (Yasuhiro Matsumoto)
author Christian Brabandt <cb@256bit.org>
date Fri, 05 Feb 2016 22:45:06 +0100
parents 00d64eb49ce1
children b74549818500
comparison
equal deleted inserted replaced
7934:1aab88611034 7935:3f2e0b62003d
1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 04 1 *channel.txt* For Vim version 7.4. Last change: 2016 Feb 05
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
30 This requires Python. The demo program can be found in 30 This requires Python. The demo program can be found in
31 $VIMRUNTIME/tools/demoserver.py 31 $VIMRUNTIME/tools/demoserver.py
32 Run it in one terminal. We will call this T1. 32 Run it in one terminal. We will call this T1.
33 33
34 Run Vim in another terminal. Connect to the demo server with: > 34 Run Vim in another terminal. Connect to the demo server with: >
35 let handle = ch_open('localhost:8765', 'json') 35 let handle = ch_open('localhost:8765')
36 36
37 In T1 you should see: 37 In T1 you should see:
38 === socket opened === ~ 38 === socket opened === ~
39 39
40 You can now send a message to the server: > 40 You can now send a message to the server: >
60 call ch_sendexpr(handle, 'hello!', "MyHandler") 60 call ch_sendexpr(handle, 'hello!', "MyHandler")
61 61
62 Instead of giving a callback with every send call, it can also be specified 62 Instead of giving a callback with every send call, it can also be specified
63 when opening the channel: > 63 when opening the channel: >
64 call ch_close(handle) 64 call ch_close(handle)
65 let handle = ch_open('localhost:8765', 'json', "MyHandler") 65 let handle = ch_open('localhost:8765', {'callback': "MyHandler"})
66 call ch_sendexpr(handle, 'hello!', 0) 66 call ch_sendexpr(handle, 'hello!', 0)
67 67
68 ============================================================================== 68 ==============================================================================
69 2. Opening a channel *channel-open* 69 2. Opening a channel *channel-open*
70 70
71 To open a channel: > 71 To open a channel: >
72 let handle = ch_open({address}, {mode}, {callback}) 72 let handle = ch_open({address} [, {argdict}])
73 73
74 {address} has the form "hostname:port". E.g., "localhost:8765". 74 {address} has the form "hostname:port". E.g., "localhost:8765".
75 75
76 {mode} can be: *channel-mode* 76 {argdict} is a dictionary with optional entries:
77 "json" - Use JSON, see below; most convenient way 77
78 "mode" can be: *channel-mode*
79 "json" - Use JSON, see below; most convenient way. Default.
78 "raw" - Use raw messages 80 "raw" - Use raw messages
79 81
80 *channel-callback* 82 *channel-callback*
81 {callback} is a function that is called when a message is received that is not 83 "callback" is a function that is called when a message is received that is not
82 handled otherwise. It gets two arguments: the channel handle and the received 84 handled otherwise. It gets two arguments: the channel handle and the received
83 message. Example: > 85 message. Example: >
84 func Handle(handle, msg) 86 func Handle(handle, msg)
85 echo 'Received: ' . a:msg 87 echo 'Received: ' . a:msg
86 endfunc 88 endfunc
87 let handle = ch_open("localhost:8765", 'json', "Handle") 89 let handle = ch_open("localhost:8765", 'json', "Handle")
88 90
89 When {mode} is "json" the "msg" argument is the body of the received message, 91 "waittime" is the time to wait for the connection to be made in milliseconds.
92 The default is zero, don't wait, which is useful if the server is supposed to
93 be running already. A negative number waits forever.
94
95 "timeout" is the time to wait for a request when blocking, using
96 ch_sendexpr(). Again in millisecons. The default si 2000 (2 seconds).
97
98 When "mode" is "json" the "msg" argument is the body of the received message,
90 converted to Vim types. 99 converted to Vim types.
91 When {mode} is "raw" the "msg" argument is the whole message as a string. 100 When "mode" is "raw" the "msg" argument is the whole message as a string.
92 101
93 When {mode} is "json" the {callback} is optional. When omitted it is only 102 When "mode" is "json" the "callback" is optional. When omitted it is only
94 possible to receive a message after sending one. 103 possible to receive a message after sending one.
95 104
96 The handler can be added or changed later: > 105 The handler can be added or changed later: >
97 call ch_setcallback(handle, {callback}) 106 call ch_setcallback(handle, {callback})
98 When {callback} is empty (zero or an empty string) the handler is removed. 107 When "callback is empty (zero or an empty string) the handler is removed.
108 NOT IMPLEMENTED YET
109
110 The timeout can be changed later: >
111 call ch_settimeout(handle, {msec})
112 NOT IMPLEMENTED YET
99 113
100 Once done with the channel, disconnect it like this: > 114 Once done with the channel, disconnect it like this: >
101 call ch_close(handle) 115 call ch_close(handle)
102 116
103 Currently up to 10 channels can be in use at the same time. *E897* 117 Currently up to 10 channels can be in use at the same time. *E897*