CQC Quick Tutorial

Dean Roddey

Informations

• Publié par: Zoed
• Nombre de lectures: 19
• Langue: English

Extrait

CQC Remote Viewer Dev Guide
Page: 1



CQC Remote Viewer Development Guide
Implementing a RIVA Client


(For CQC Version 3.4)

Last Edited on: November 11, 2010
Copyright © Charmed Quark Systems, 2009..2010 CQC Remote Viewer Dev Guide
Page: 2
Table of Contents
Table of Contents ...................................................................................................... 2
Content Summary ...... 4
Preliminary Notes ...... 4
Revisions ................. 4
The Big Picture ......... 5
Protocol Basics 5
Protocol Details ........................................................................................................ 7
Logon Protocol .......... 9
Client Information . 10
Validation Login ... 10
Graphics Output ...... 12
General Display Strategies ....................................................................................... 12
Scope Based Operations .......................... 12
Fonts ................................................ 13
Clipping Areas ...................................................................... 13
Images............... 13
Limited Capability Clients ..................... 14
Persistent Connections ......................................................................................... 14
Display Strategy . 15
Downloading Images ............................ 15
Image Masks ..................................... 15
User Input ............................................................................. 16
Protocol Reference .. 17
TAlphaBlit – ...... 18
TDrawBitmap – .. 19
TDrawLine – ...... 20
TDrawMultiText – ............................................................................................... 21
TDrawText – ..................................... 22
TDrawTextFX – .. 23
TEndDraw – ...... 24
TException – ..... 25
TFillArea –........................................................................ 26
TFillWithBmp – .. 27
TGenOpcode – ................................... 28
TGradientFill – .. 29
THeader – ........ 30
TLoginRequest, TLoginResponse, TLoginStatus – ........................................................... 31
TMaskedAlphaBlit – ............................................................. 32
TPushClipArea – . 33
TPushFont – ...................................... 34
TReqImgDownload,TRemImgStart – .......................................... 35
TSetBackMixMode, TSetMixMode, TSetColor – .............................. 37
TShowMsg – ...................................... 38
TSpecialAction – . 39
Copyright © Charmed Quark Systems, 2009..2010 CQC Remote Viewer Dev Guide
Page: 3
TStatusReturn – ................................................................................................. 40
TStrokeArea – .... 41
TTextInfo – ....... 42
TTouchEvent – ... 43
Protocol Version 2.... 44
General Issues ...................................................................................................... 44
New Messages ...... 44
TDrawPBar – ..... 44
TNewTemplate – 45
Appendix A – Simple Clients ........................................................................................ 46
Snapshot Downloads .............................. 46
Optimization ....................................................................................................... 47
Copyright © Charmed Quark Systems, 2009..2010 CQC Remote Viewer Dev Guide
Page: 4
Content Summary
This document is intended for developers who wish implement a client for the CQC Remote Interface Viewer Architecture (RIVA) protocol.
RIVA clients can display CQC graphical interfaces with very minimal understanding of CQC itself, since almost all of the work is done by
the RIVA Server that the clients connect to. So they are a practical means to access CQC user interfaces on non-Windows platforms.
The protocol does not require any of our code on your side of the connection. It is a pure ‘on the wire’ protocol, so you can use it from any
device that can open sockets and can provide sufficient graphical operations to display the content (or at least the amount of content
required for the type of templates the device will be used to display.)
Preliminary Notes
 To use the protocol, you must have installed the Remote Viewer Server. This is one of the optional features you can select
when installing CQC.
 Generally, you would install a single instance on the master server, but you can install it on some other server and you can
install multiple instances of it in the network, if that is warranted (not on the same machine, but a single instance on more than
one machine.) You will attach to the server in the usual way, by getting the address of the target host and opening a socket.
 The more remote viewer clients you have, the more likely you will want to distribute the load, or perhaps have a dedicated
remote viewer server to take that load off the master server.

Revisions
Version revisions are presented at the end of the document, so as to make the changes very clear. Each version has its own section that
just contains the changes for that version.
Version 2: Initially in beta 3.31, released formally for version 3.4.
Copyright © Charmed Quark Systems, 2009..2010 CQC Remote Viewer Dev Guide
Page: 5
The Big Picture
Before getting into the details, first we'll cover the reason for the remote viewer system, the basic functionality provided, and the general
structure of a client that would use this API. The reason that the Remote Viewer system exists is that the CQC user interface system is
very rich and powerful. To replicate this functionality on multiple platforms would be an enormous job, and for all of these platform specific
implementations to keep up with changes to the CQC interface system would be very unlikely. The existing native Interface Viewer
engine and associated viewer program is 50,000 lines of code, and that leaves aside an equal or greater amount of code in underlying
layers of the product that it shares with other CQC programs., which any third party implemented native viewer would have to replicate.
But we clearly need to provide access to our rich user interfaces on other platforms, and rewriting 850,000 lines of code in another
language wasn’t a remote possibility. The remote viewer system is a means of addressing this problem. If you are familiar with systems
like X-Windows or Windows RDP, the remote viewer protocol is not unlike those, where only the graphics operations are transmitted to
the client display, while the actual work is done on the server machine.
Unlike X-Windows or RDP though, our scope is far more limited. So the number of commands required is not large and many
optimizations are possible. A typical remote viewer client might be somewhere in the range of 2000 to 4000 lines of code. Not trivial, but
that includes general purpose utility code required on any platform to create a new application and graphical interface and so forth. And
it’s far less than the probably 50,000 lines or more that would be required to implement a full viewer client.
Equally importantly, unless new graphical commands are required, and that’s not terribly likely, any new features added to the user
interface system will immediately be supported by the remote viewer client, since it only has to understand how to perform the low level
graphical operations involved in displaying that new feature. So we are not hamstrung in our expansion of the interface system because
we are afraid we will break existing remote viewer clients.
There are two ‘versions’ of the protocol, one for more advanced clients which will offer maximum performance, where the client does all of
the drawing and only raw graphics commands are transmitted. Such clients need to be able to handle alpha channel based graphics and
be capable of multi-threaded operations. There is also a simpler version where the server does the actual drawing and the client is just
informed when areas have changed, and ask for snapshots of those areas.
In both cases it would be necessary to support double buffering of graphical output in order to maintain good performance. On some
platforms that is just an inherent aspect of the GUI and on others it is something that programs do for themselves.
Protocol Basics
The protocol uses a socket interface. The server will be listening on the port it was set to during the install, so a client would want to open
a stream oriented socket, using the TCP protocol, on that port, using the address of the host on which the server is running. As soon as
you open the socket, your client must immediately do a logon to the CQC system.
This is a two step process, the details of which will be discussed below. In the CQC system, a 'security token' is required in order for a
client to do most operations. Since the remote viewer clients are not native CQC applications, they cannot understand the security token
or be completely trusted for that matter, so the server itself will act as the client's proxy in the CQC system, holding the security token on
the client's behalf and using it where required. As long as the client holds the socket open after a legal logon, the security token will be
maintained.
All messages passed b