BLAISE

BLAISE PASCAL MAGAZINE 41

PASCAL MAGAZINE
D E L P H I, L A Z A R U S, O X Y G E N E, S M A R T M O B I L E,
A N D P A S C AL R E L A T E D L A N G U A G E S
A N D R O I D, I O S, M A C, W I N D O W S & L I N U X

Alan Turing June 23, 1912

AlanTuring 23 6 1912
23 Alan 6 Turing 1912
@23Alan6TuringMCMXII
@23Alan6TuringMcmX2!
@23A6TMcmX2!

SECURITY AND SAFETY IN APPLICATIONS - BY ANDREA RAIMONDI

B E G I N N I N G O F T I M E . . . T H E W AT E R C L O C K - B Y E D I T O R
THE NEW LAZARUS 1.4 - BY EDITOR
SECURITY IN APPLICATIONS: PASSWORD HANDLING
- BY ANDREA RAIMONDI

IN REMEMBERANCE OF OF ALAN TURING - BY EDITOR

LAZARUS NOW CAN USE GOOGLE APIS

REST CLIENTS: USING THE GOOGLE APIS IN FREE PASCAL
- BY MICHAEL VAN CANNEYT

ARDUINO: THE VISUINO PROJECT - PART 1

BY BOIAN MITOV
WORKING WITH GOOGLE MERCHANTS RATING DATA USING KBMMW
BY KIM MADSEN

PRINTED ISSUE PRICE 15,00

DOWNLOAD ISSUE PRICE 5,00
BLAISE
BLAISE PASCAL MAGAZINE 41
PASCAL MAGAZINE
D E L P H I, L A Z A R U S, S M A R T M O B I L E S T U D I O,
A N D P A S C A L R E L A T E D L A N G U A G E S
F O R A N D R O I D, I O S, M A C, W I N D O W S & L I N U X

CONTENTS

Articles
SECURITY AND SAFETY IN APPLICATIONS
- BY ANDREA RAIMONDI - PAGE 5
BEGINNING OF TIME...THE WATER CLOCK
- BY EDITOR - PAGE 9
THE NEW LAZARUS 1.4
- BY EDITOR - PAGE 14
SECURITY IN APPLICATIONS: PASSWORD HANDLING
- BY ANDREA RAIMONDI - PAGE 18
IN REMEMBRANCE OF OF ALAN TURING
- BY EDITOR - PAGE 23
LAZARUS NOW CAN USE GOOGLE APIS
REST CLIENTS: USING THE GOOGLE APIS IN FREE PASCAL
- BY MICHAEL VAN CANNEYT - PAGE 25
ARDUINO: THE VISUINO PROJECT - PART 1
- BY BOIAN MITOV - PAGE 37
WORKING WITH GOOGLE MERCHANTS RATINGDATA USING KBMMW
- BY KIM MADSEN - PAGE 43

MOTION

BLAISE
BLAISE PASCAL
PASCAL MAGAZINE
MAGAZINE

Advertisers

Barnsten 4
BetterOffice 21
Components 4 Developers 48
Computer Math & Games 4
Daniel Teti 47
Raize Software 8 Publisher: Foundation for Supporting the Pascal Programming Language
Visuino MITOV 22 in collaboration with the Dutch Pascal User Group (Pascal Gebruikers Groep)
Stichting Ondersteuning Programmeertaal Pascal

2 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

Stephen Ball Peter Bijlsma Michal Van Canneyt,
http://delphiaball.co.uk -Editor peter @ blaisepascal.eu michael @ freepascal.org
@DelphiABall

Marco Cant David Dirkse Benno Evers

www.marcocantu.com www.davdata.nl b.evers
marco.cantu @ gmail.com E-mail: David @ davdata.nl @everscustomtechnology.nl

Bruno Fierens Primo Gabrijeli Cary Jensen

www.tmssoftware.com www. www.jensendatasystems.com
bruno.fierens @ tmssoftware.com primoz @ gabrijelcic.org http://caryjensen.blogspot.nl

Max Kleiner John Kuiper Wagner R. Landgraf

www.softwareschule.ch wagner @ tmssoftware.com
max@kleiner.com

Kim Madsen Peter van der Sman Jeremy North

www.component4developers jeremy.north @ gmail.com

Detlef Overbeek - Editor in Chief Howard Page Clark Andrea Raimondi

www.blaisepascal.eu E-mail: hdpc @ talktalk.net andrea.raimondi @ gmail.com
editor @ blaisepascal.eu

Wim Van Ingen Schenau Rik Smit Bob Swart

-Editor rik @ blaisepascal.eu www.eBob42.com
wisone @ xs4all.nl Bob @ eBob42.com

Daniele Teti
www.danieleteti.it
d.teti@bittime.it

Please note: extra space characters have been deliberately added around the @ symbol in
these email addresses, which need to be removed if you use them.
editor @ blaisepascal.eu
Authors - Christian name in alphabethical order
A Andrea Raimondi , L Wagner R. Landgraf, Sergey Lyubeznyy
B Stephen Ball, Peter Bijlsma, Dmitry Boyarintsev K Max Kleiner
C Michal Van Canneyt, Marco Cant, M Kim Madsen, Felipe Monteiro de Cavalho
D David Dirkse, Daniele Teti N Jeremy North,
F Bruno Fierens O Inoussa Ouedraogo
G Primo Gabrijeli, Mattias Gaertner P Howard Page-Clark,
H Fikret Hasovic S Rik Smit, Bob Swart,
J Cary Jensen Z Siegfried Zuhr

Editor - in - chief
Detlef D. Overbeek, Netherlands Tel.: +31 (0)30 890.66.44 / Mobile: +31 (0)6 21.23.62.68
News and Press Releases email only to editor@blaisepascal.eu

Editors
Peter Bijlsma, W. (Wim) van Ingen Schenau, Rik Smit,
Correctors
Howard Page-Clark, James D. Duff
Trademarks
All trademarks used are acknowledged as the property of their respective owners.
Caveat Whilst we endeavour to ensure that what is published in the magazine is correct, we cannot accept responsibility for any errors or omissions.
If you notice something which may be incorrect, please contact the Editor and we will publish a correction where relevant.
Subscriptions ( 2013 prices )
1: Printed version: subscription 65.-- Incl. VAT 6 % (including code, programs and printed magazine,
10 issues per year excluding postage).
2: Electronic - non printed subscription 45.-- Incl. VAT 21% (including code, programs and download magazine)

Subscriptions can be taken out online at www.blaisepascal.eu or by written order, or by sending an email to office@blaisepascal.eu
Subscriptions can start at any date. All issues published in the calendar year of the subscription will be sent as well.
Subscriptions run 365 days. Subscriptions will not be prolonged without notice. Receipt of payment will be sent by email.
Subscriptions can be paid by sending the payment to:
ABN AMRO Bank Account no. 44 19 60 863 or by credit card: Paypal
Name: Pro Pascal Foundation-Foundation for Supporting the Pascal Programming Language (Stichting Ondersteuning Programeertaal Pascal)
IBAN: NL82 ABNA 0441960863 BIC ABNANL2A VAT no.: 81 42 54 147 (Stichting Programmeertaal Pascal)
Subscription department Edelstenenbaan 21 / 3402 XA IJsselstein, The Netherlands / Tel.: + 31 (0) 30 890.66.44 / Mobile: + 31 (0) 6 21.23.62.68
office@blaisepascal.eu

Copyright notice
All material published in Blaise Pascal is copyright SOPP Stichting Ondersteuning Programeertaal Pascal unless otherwise noted and may
not be copied, distributed or republished without written permission. Authors agree that code associated with their articles will be made
available to subscribers after publication by placing it on the website of the PGG for download, and that articles and code will be placed on
distributable data storage media. Use of program listings by subscribers for research and study purposes is allowed, but not for commercial
purposes. Commercial use of program listings and code is prohibited without the written permission of the author.

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 3

CALLING ALL VCL DEVELOPERS!
Whether you are building new software, or updating existing applications, RAD Studio XE8 is a must! Quickly update
and extend your existing VCL based Windows applications to create modern, connected app solutions for Windows and
beyond! Try it with your complimentary 30-day license now!

Must-Have Features For VCL Developers in NEW RAD Studio,

Delphi and C++Builder Xe8

NEW! MORE THAN 20 NEW IDE FEATURES FOR CODING PRODUCTIVITY:

Code faster and more efficiently with new refactorings, multi-paste support, clipboard history, parenthesis matching,
Smart Keys, Code Navigation Toolbar, project statistics and more!
ENHANCED! THE VCL AND FMX RTL GETS BETTER AND YOU BENEFIT BIG TIME:
The RTL has better performance, parallel support, native HTTP/S and Bluetooth, optimized Generics collections and
much more
NEW! GETIT PACKAGE MANAGER: ACCESS AND INSTALL FROM THE CLOUD,
popular VCL and FMX source code libraries, components and tools like AsyncPro and Power PDF right from within the
IDE. Get the updated TurboPack for free!
ENHANCED! APP TETHERING:
Now it's easier than ever to extend your VCL and FMX desktop application UI, data and control to mobile and wearables
via WiFi, ethernet or Bluetooth
NEW! APPANALYTICS:
Finally understand exactly how your customers use your VCL or FMX app. Simply add the TAppAnalytics component
and get instant access to application usage statistics through your cloud dashboard
RECENTLY ADDED! Easily Add Parallel Processing
to Your New and Existing VCL Apps: Delivering 2x to 8x performance gains on Multi-Core systems
NEW! NATIVE PLATFORM HTTP/S VCL/FMX SUPPORT FOR WINDOWS, MAC, IOS AND
ANDROID: Makes must-have secure connections a snap
ENHANCED! MBAAS CLOUD SERVICES:
Easily power your VCL and FMX desktop and mobile application backend infrastructure in the cloud with user
management, push notifications, data storage and more
NEW! IOT, BEACONS AND MORE:
Easily add IoT gadgets and sensors, like proximity beacons, into your existing Windows VCL and FMX appsNEW! Unit
Testing: It's has never been easier or more complete with the new integrated DUnitX testing framework
ENHANCED! FireDAC:
The best DAC gets better with Updates Management, dbExpress migration, SQLite encryption, InterBase XE7 Change
Views and more
ENHANCED! EMS (Enterprise Mobility Services):
Easily integrate your applications to your enterprise and to the world with Push Notifications, REST API publishing,
external credentials, database connection pooling, client API component, new administrative app and more
ENHANCED! Docs, Samples and Technical Content:
Learn what you can do and how to do it with more tech docs and videos than ever before
NEW! Update Subscription:
Take advantage of Update Subscription to stay up-to-date with latest versions, updates for older product versions and
much more

or call: +31 (0)235422227

http://www.barnsten.com/default/newxe8
 SECURITY AND SAFETY IN APPLICATIONS BY ANDREA RAIMONDI (PAGE 1)
Introduction
There is a gigantic misconception based off the
fact many developers think that to enable
security you need to use a library. While that
surely is part of what you need to do, it's by far
not the only thing, because security is so much
more than that.
Security and Safety
When we talk about security and safety we really
refer to two different things: security is about
the environment around you, while safety is
about you. They are often used (wrongly)
interchangeably because of this lack of
understanding. So, when we say that data must
be secure, we are saying that there has to be no
way to arrive at a situation where it can be
grabbed hold of from people who should not
have access to it.
If that happens, then the data must also be safe,
i.e. it must be difficult (or impossible) to use by
said people or their associates.
The Internet
Let's get this straight: in the Internet age, data is
neither secure nor safe ever. Just accept this and
realise all you can do is to make it really difficult to
actually break in and/or use the data.
What do we mean, then, when we say that the data
is secure and/or safe in an Internet setting? What
we are really saying (or better, what we should be
saying, alas some companies still try to sell snake
oil) is that the data is not attractive enough to
malignant parties to be worth their time.
Data Attractiveness
What makes data attractive to malicious users?
There are two main traits which play a role in how
attractive a data set is: ease of grab and potential; if
the data is easy to grab and with a lot of potential
then malicious parties have a really strong interest
in getting it. On the other hand, if the data is
extremely difficult to grab and/or has little
potential, then they do not have as much interest in
getting hold of it, making it more secure and more
safe in the process.So let's just make an example of
each and see how your data fits in the picture:
Easy and High Potential
A website called We store your credit cards has a
login form which shows SQL errors. When you go
into your profile, you can see your password in
clear text. It reminds you of your credit card
number and security code. Why is that an attractive
target? The fact it shows SQL errors means there is
no protection from SQL Injection, which means that
you can try to log in with credentials you do not
own.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
Once you do that, you can browse the site looking
for clues and finding an admin password to get
inside the hosting panel. Once there, you are King:
you can download the database and crack the
passwords, plus getting C/C numbers in the
process. Here we really have two datasets a
malicious user is interested in: the password list
and the credit card numbers. I don't need to
explain why the second is attractive, but what
about the password list? Why is it so attractive?
Well, the thing is that humans stubbornly demand
to be humans, so they want an easy life. Because of
this, they are probably using for that site the same
password they are using elsewhere, for instance in
their home banking. Get it now? It is not always
about the single site they are attacking, more often
is about the knowledge they can acquire.
Hard and Low Potential
The original website has been hacked and the
black market has been flooded with credit card
numbers. A group of investors, however, thinks
there is potential in the site's concept, if only
things could be made in a way that allowed them
to avoid the mistakes of the past. So they bring in a
security expert who makes the following changes:
Passwords cannot be retrieved anymore,
they have to be reset.
SQL errors aren't showing anymore.
The only acceptable C/C numbers are those
of virtual cards, which are generated by the
home banking or those which also input you
for a password (which is not stored in the DB)
These changes alone make all the difference: the
fact you have to reset the password means that it
has been hashed, so it's not easy to recover. Also,
the fact you only accept virtual c/c numbers or
real ones that need a confirmation password
means that they are essentially useless. For virtual
cards, if a break-in happens, they can easily be
disabled and made useless as well.
As you can see, a few changes make the data
harder to get and with very little value in case of a
break in. The thing here is that now, they only get
one potentially promising set of data instead of
two, because even if the admins do not realise
soon of the break in, there is just so much money
that criminals can sell a lot less than on real
credit cards. Also, if the virtual and real numbers
are not clearly identified in the DB, this makes all
of them useless, because there is no way criminals
can distinguish them without using them,
therefore exposing the fact that a break-in has
occurred.
5
SECURITY AND SAFETY IN APPLICATIONS (PAGE 2)
Think Holistically*
When you are designing an application or website,
security and safety should be among the design
considerations. If you are accepting an extranet
login, for instance, you need to hash your
passwords with an algorithm that isn't easy to
break in, i.e. that is secure. Hence, you can't use
MD5 or SHA1 for example. That's a really bad
idea. You really should be using SHA2 or SHA256.
Or, if you are using an insecure algorithm for
some reason, then you ensure you can use it with
an HMAC. HMACs have this beautiful property of
being secure even if you use an insecure hash
function.
(* Holism Chiefly Philosophy:The theory that parts of a
whole are in intimate interconnection, such that they
cannot exist independently of the whole, or cannot be
understood without reference to the whole, which is
thus regarded as greater than the sum of its parts. )
But logins are just the tip of the iceberg.
How about the JavaScript? Are you passing
JavaScript functions in your JSON and calling
eval?
That's another no-no because it's dangerous.
What happens if the data is valuable and a
malicious user breaks in on the server and adds a
PHP file and injects a malicious JavaScript
function?
How about the structure of your website?
If you can upload files, are you keeping them in a
safe place and using an internal script which is
allowed to fetch them or are you keeping them in
a place where they can be grabbed?
And your webpages, are you enforcing security
for really important pages? Or are you letting
anyone browse to userlist.php?
Desktop applications aren't exempt either from
this sort of problems. Where are you storing your
files? Are you taking measures to make them
difficult to use? Are you storing them in a binary
or text format? Binary formats are inherently more
difficult to handle, it requires skill.
What database are you using? Are you using
Firebird, which allows an attacker to download
the db and use his/her own security accounts to
read it or are you using Oracle, where you can
only do that AFTER you have exported the
database (hence requiring a correct account in the first
place)?
And are your database accounts safe? Are you
using SQL Server with Windows Authentication,
which means that if a malicious user gets hold of
your Windows account he/she can roam free in
the DB as well?
6 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
There are so many things that can potentially go
wrong and these are just a start.
Users and Roles
Let me get back to this for a minute please. One
thing is the database users and another is
application users.
There are two schools of thought in this: one says
Every application user should be associated to a
database user and the other says: No way,
application users are one thing and database users
are another. Of the two, under a security point of
view, the latter is correct. Why should an
application user have an account on the database?
Using social engineering, a malicious user could
approach an application user who is elevated
enough to cause havoc. This is a very bad idea.
This is why we have roles see. Your identity and
your role are (and should always be) two different
things. It makes sense in everyday life, where we
experience it all the time, why should it be any
different in applications?
Application Screens
There is this really bad tendency to make
applications that operate in light mode until a
serial number is typed in where they become fully
operational. This is a very dangerous way of
making software, because there is a respected and
long tradition among criminals of checking serial
numbers and deriving key generators. I do not like
this at all because I think it's way too easy to break
the mould and be a leecher.
So, what should you be doing? Well, for a start,
you should have two versions: one for the light and
the other for the fully functioning one. It is really
easy to split forms so that there's one you can use in
the light version and an inherited one which you
can use in the full. It is not difficult to do and yields
great results. That is not all, however. Each screen
should only have an associated menu item visible if
your role allows it. And you should check user and
role when loading the form, so that if they do not
match the expected ones a message can be
displayed saying the user is not authorized and
then unloaded gracefully. This is because there are
ways to make a menu item appear on Windows, it
has been done before.
Licensing
Another issue is licensing. I have seen, again, a
disturbing trend of having online activations, user
harassment etc., all in the name of revenue. This
means we punish the good guys while the bad ones
get mostly away with it, because you know
these things can be removed most of the time.
SECURITY AND SAFETY IN APPLICATIONS (PAGE 3)
There are ways to do it, because I still see pirated
copies of software floating around so it's not like
they serve a purpose. They only make life difficult
for honest people who purchase their stuff. And
they come at an incredibly high cost because this
stuff doesn't cost peanuts. I have also seen
madness such as, for example, encrypted
executables and things like this.
That's completely bonkers because it makes
memory management in Windows a mess. So,
how do we solve this? It's pretty simple actually:
just use decent serial numbers that work locally
and that are detached from the working machine.
When you need to check that the serial
number is ok, then pop up a box asking for the
email addressed used in registration and match it
against the available serial numbers.
If the number is available and it's the first time a
check occurs, then it's very likely a legit user who
wasn't yet registered. If it's not available or if the
email is different from what it should be, then it's
very likely a pirate. You can also offer the option
to register straight away, so that the following
checks are performed directly against the taken
serial numbers.
When you make the serial number and
activation code independent from the machine,
you make computer upgrades possible easily. You
also make the user less frustrated and less
worrisome. You can provide a way to enter a
username and password and download the
registration number, so that they don't even have
to back it up to re-enter it. Make it easy on them.
All you want is to have legitimate users. That
is all which counts. Ideally, users should not even
have to see their registration number. They
shouldn't have to care.
Convenience trumps security
every time
Then there's the problem of convenience. Should
we allow a user to log in automatically? What
happens if an XSS attack steals the login cookie?
Should we track the IPs? Should we restrict the
functionality only to the same IP and if it changes
for any reason they need to log in again?
Users love convenience and some of the
above advice goes just in this direction: it is very
convenient for users not to have to back-up a
serial number and just you know log in from
the application to grab it. Other things, however,
go against convenience: the roles, checking and
making sure that forms work with the correct
users, etc.
What may happen in some cases is that
someone is given a role that he/she should not
have just to access a certain form, while in the
process putting everyone at risk because of the
increased privilege.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
So should we do something like being able to
associate forms to roles so that users can get what
they want while not increasing the risk too much?
There are cases, however, where I feel that
developers should put their feet down and just flat
out refuse to do something on security grounds.
Better yet, if you can, make the user sign a
document where they recognize you were against
something on security grounds and they wanted it
anyway; If possible, make them sign it in blood
(yes, I am serious, DNA always works in court).
Before getting to that, however, always try to
explain clearly why you are refusing something on
security grounds. When I was living in Naples,
Italy, I was in an apartment block. On the floor just
below ours, a judge lives who has two internet
connections: his home one and the other one
connected to the tribunal.
He was whining at me of this, saying he
couldn't download or install anything on this
special machine. He was suffering it because he
didn't understand the problem. So I stopped him
and said How would you like if someone
connected to the tribunal using your account and
wrote the motivation to a judgement instead of
you? He went pale and said Don't even joke
about that. This is when I told him the Internet is
a dangerous place. This is why that machine is
limited, to avoid even the chance something like
that happens. He hasn't whined about it since.
Is it worth it?
Now, we have discussed a few principles that
should really be considered when doing
applications or websites. These things, however,
are absolutely not free, so what you do or not do
also has to depend on your financials. Is it worth,
for example, to add role checking to all forms?
Maybe yes, if you are doing an accounting
package, or maybe not If you are simply doing a
personal ledger.
Also, can you afford for example to only
check serial numbers when the internet is
connected? Again, maybe yes or maybe not,
depends on your circumstances. There are cases,
for example, where you really need to check that a
user is licensed to use a certain application, but
those cases are only about situations where
computers do not change often and where
connectivity is not an issue. So, each application
should weigh in the advantages against the
disadvantages of a certain approach.
Striking a balance is very difficult and
sometimes you make the wrong decisions. It
happens all the time, so you should be able to
change your mind when your situation changes:
an open mind is always an asset, ever so much so
in security.
7
BLAISE 2015
 THE WATER CLOCK PAGE 1
In this article series I will try to inform you about
very important , yet not very well known subjects
of the time line we showed in the last item (NR. 40).
This time the water clock is the subject:
I suppose you never realized that very ancient people
already new about time and measuring it.
It goes as far back as to 4500 BC (before Christ) as far
as the documentation reaches. Most of the
documentation that follows is gathered trough the
internet and sometimes through books. We thank te
authors for that and making it available:
http://en.wikipedia.org/wiki/Water_clock
http://fourriverscharter.org/projects/Inventions/pages/
china_waterclock.htm.
Surely there is more to be found , but this illustrates
much of the knowledge we have about this subject.
One last thing is there to be said: the not being
scalable of the water clock is the reason that it took so
long before time was in use for all people:
the invention of the mainspring in the early 15th
century allowed portable clocks to be built, evolving
into the first pocketwatches by the 17th century, then
it became possible to create a portable clock and from
there on it was an invention that became available
even on your espresso machine.
A water clock or clepsydra (Greek kleptein) is any
timepiece in which time is measured by the regulated
flow of liquid into or out from a vessel where the amount
is then measured.
Water clocks, along with sundials, are likely to be the
oldest time-measuring instruments. Where and when
they were first invented is not exactly known, and given
their great antiquity it may never be.
The bowl-shaped outflow is the simplest form of a
water clock and is known to have existed in Babylon and
in Egypt around the 16th century BC. Other regions of the
world, including India and China, also have early
evidence of water clocks, but the earliest dates are less
certain. Some authors, however, claim that water clocks
appeared in China as early as 4000 BC. -(Cowan, Harrison
J. (1958). "Time and Its Measurement: From the stone age to
the nuclear age". Ohio: The World Publishing Company.)
Some modern timepieces are called "water clocks"
but work differently from the ancient ones. Their
timekeeping is governed by a pendulum, but they use
water for other purposes, such as providing the power
needed to drive the clock by using a water wheel or
something similar, or by having water in their displays.
The Greeks and Romans advanced water clock design to
include the inflow clepsydra with an early feedback
system, gearing, and escapement mechanism, which were
connected to fanciful automata and resulted in improved
accuracy.
Further advances were made in Byzantium, Syria
and Mesopotamia, where increasingly accurate water
clocks incorporated complex segmental and epicyclic
gearing, water wheels, and programmability, advances
which eventually made their way to Europe.
Independently, the Chinese developed their own
advanced water clocks, incorporating gears, escapement
mechanisms, and water wheels, passing their ideas on to
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
Korea and Japan. Some water clock designs were
developed independently and some knowledge was
transferred through the spread of trade. These early
water clocks were calibrated with a sundial.
Figure 1: Ancient Persian clock
Persia
According to Callisthenes, the Persians were using water
clocks in 328 BC to ensure a just and exact distribution of
water from qanats to their shareholders for agricultural
irrigation. The use of water clocks in Iran, especially in
Zeebad, dates back to 500BC. Later they were also used to
determine the exact holy days of pre-Islamic religions,
such as the Nowruz, Chelah, or Yald - the shortest,
longest, and equal-length days and nights of the years.
The water clocks used in Iran were one of the most
practical ancient tools for timing the yearly calendar. The
water clock, or fenjaan, was the most accurate and
commonly used timekeeping device for calculating the
amount or the time that a farmer must take water from a
qanat or well for irrigation, until it was replaced by more
accurate current clocks.
Persian water clocks were a practical and useful tool
for the qanat's shareholders (A qant is one of a series of
well-like vertical shafts, connected by gently sloping tunnels.
Qants create a reliable supply of water for human settlements
and irrigation in hot, arid, and semi-arid climates) to calculate
the length of time they could divert water to their farm.
Therefore a very fair and clever old person was elected to
be the manager of the water clock(MirAab), and at least
two full-time managers were needed to control and
observe the number of fenjaans and announce the exact
time during the days and nights.
The fenjaan consisted of a large pot full of water and a
bowl with a small hole in the center. When the bowl
became full of water, it would sink into the pot, and the
manager would empty the bowl and again put it on the
top of the water in the pot. He would record the number
of times the bowl sank by putting small stones into a jar.
The place where the clock was situated, and its managers,
were collectively known as khaneh fenjaan. Usually this
would be the top floor of a public-house, with west- and
east-facing windows to show the time of sunset and
sunrise. There was also another time-keeping tool named
a staryab or astrolabe, but it was mostly used for
superstitious beliefs and was not practical for use as a
farmers' calendar. The Zeebad Gonabad water clock was
in use until 1965 when it was substituted by modern
clocks.
9
THE WATER CLOCK PAGE 2
Egypt
The oldest water clock of which there is physical evidence
dates to c. 1417-1379 BC, during the reign of Amenhotep
III where it was used in the Temple of Amen-Re at
Karnak. The oldest documentation of the water clock is
the tomb inscription of the 16th century BCE Egyptian
court official Amenemhet, which identifies him as its
inventor. These simple water clocks, which were of the
outflow type, were stone vessels with sloping sides that
allowed water to drip at a nearly constant rate from a
small hole near the bottom. There were twelve separate
columns with consistently spaced markings on the inside
to measure the passage of "hours" as the water level
reached them. The columns were for each of the twelve
months to allow for the variations of the seasonal hours.
These clocks were used by priests to determine the time at
night so that the temple rites and sacrifices could be
performed at the correct hour.[8] These clocks may have
been used in daylight as well.
Figure 2: Water clock calculations by Nab-apla-iddina
Babylon
In Babylon, water clocks were of the outflow type and
were cylindrical in shape. Use of the water clock as an aid
to astronomical calculations dates back to the Old
Babylonian period (c. 2000 BC- 1600 BC).
While there are no surviving water clocks from the
Mesopotamian region, most evidence of their existence
comes from writings on clay tablets. In these tablets,
water clocks are used in reference to payment of the night
and day watches (guards).
These clocks were unique, as they did not have an
indicator such as hands (as are typically used today) or
grooved notches (as were used in Egypt). Instead, these
clocks measured time "by the weight of water flowing
from" it. The volume was measured in capacity units
called qa. The weight, mana (the Greek unit for about one
pound), is the weight of water in a water clock.
It is important to note that during Babylonian times,
time was measured with temporal hours. So, as seasons
changed, so did the length of a day. "To define the length
of a 'night watch' at the summer solstice, one had to pour
two mana of water into a cylindrical clepsydra; its
emptying indicated the end of the watch. One-sixth of a
mana had to be added each succeeding half-month.
At equinox, three mana had to be emptied in order to
correspond to one watch, and four mana were emptied
for each watch of the winter solstitial night."
10
India
N. Kameswara Rao suggests that pots excavated from
Mohenjo daro might have been used as water clocks;
they are tapered at the bottom, have a hole on the side,
and are similar to the utensil used to perform
abhishekam (pour holy water) on shivalingam.
It is suggested that the use of the water clock in ancient
India is mentioned in the Atharvaveda from the 2nd
millennium BC. Ghati or Kapala (clepsydra or water clock)
is referred to in Jyotisha Vedanga, where the amount of
water that measures a nadika (24 minutes) is mentioned.
A more developed form of the clepsydra is described in
the Suryasiddhanta. At Nalanda, a Buddhist university,
four hours a day and four hours at night were measured
by a water clock, which consisted of a copper bowl
holding two large floats in a larger bowl filled with
water. The bowl was filled with water from a small hole
at its bottom; it sank when completely filled and was
marked by the beating of a drum at daytime.
The amount of water added varied with the seasons and
this clock was operated by the students of the university.
The description of a water clock in astrologer
Varahimira's Pancasiddhantika (505) adds further detail
to the account given in the Suryasiddhanta.
Figure 3: Chinese Water clock model
China
The water-powered mechanism of Su Song's
astronomical clock tower, featuring a clepsydra tank,
waterwheel, escapement mechanism, and chain drive to
power an armillary sphere and 113 striking clock jacks to
sound the hours and to display informative plaques
In China, as well as throughout eastern Asia, water
clocks were very important in the study of astronomy
and astrology. The oldest reference dates the use of the
water-clock in China to the 6th century BC. From about
200 BC onwards, the outflow clepsydra was replaced
almost everywhere in China by the inflow type with an
indicator-rod borne on a float.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
THE WATER CLOCK PAGE 3
Huan Tan (40 BCE 30 CE), a Secretary at the Court in
charge of clepsydrae, wrote that he had to compare
clepsydrae with sundials because of how temperature
and humidity affected their accuracy, demonstrating
that the effects of evaporation, as well as of temperature
on the speed at which water flows, were known at this
time. In 976, Zhang Sixun addressed the problem of the
water in clepsydrae freezing in cold weather by using
liquid mercury instead. Again, instead of using water,
the early Ming Dynasty engineer Zhan Xiyuan (c. 1360-
1380) created a sand-driven wheel clock, improved
upon by Zhou Shuxue (c. 1530-1558).
The use of clepsydrae to drive mechanisms illustrating
astronomical phenomena began with Zhang Heng (78-
139) in 117, who also employed a waterwheel.
Zhang Heng was the first in China to add an extra
compensating tank between the reservoir and the inflow
vessel, which solved the problem of the falling pressure
head in the reservoir tank. Zhang's ingenuity led to the
creation by Yi Xing (683727) and Liang Lingzan in 725
of a clock driven by a waterwheel linkwork escapement
mechanism.
The same mechanism would be used by Su Song
(10201101) in 1088 to power his astronomical clock
tower, as well as a chain drive. Su Song's clock tower,
over 30 feet (9.1 m) tall, possessed a bronze power-
driven armillary sphere for observations, an
automatically rotating celestial globe, and five front
panels with doors that permitted the viewing of
changing mannequins which rang bells or gongs, and
held tablets indicating the hour or other special times of
the day.
Today, in Beijing's Drum Tower an outflow clepsydra is
operational and displayed for tourists. It is connected to
automata so that every quarter-hour a small brass statue
of a man claps his cymbals.
Figure 4: The water-powered mechanism plans
of Su Song's astronomical clock tower,
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
The water clock created by Su Song in 1088 was one of
the most important and desired inventions of its time.It
took Su Song approximately 12 years to build an
amazingly detailed water clock. Those 12 years that Su
Song was building his water clock he also took the time
to draw out plans to build his magnificent clock. His
clock was a very complicated thing. It included 117
manikins that came out of the tower every hour on the
hour and banged gongs and rang bells or carried a tablet
that said the hour. It was powered by an 11 foot water
wheel with 36 buckets of water mounted on its
perimeter.
The clock's water wheel only turned 100 times a day and
was able to keep time relatively accurately. Su Song's
clock not only kept time but allowed people to observe
constellations that were important to Chinese astrology.
Su Song built his astronomical water clock in 1088, and
for 79 years the amazingly complicated clock stood in
the capital. One day the Jin army came and
disassembled the clock and brought the pieces to their
capital which is modern day Beijing .
They weren't able to rebuild it because of the complexity
of the clock. They might have been able to manage if
they had taken the plans with them. The fact that it was
stolen suggests that it was a very important invention
and since it was impossibleto be rebuilt it must have
been extremely complicated.
People today have tried to rebuild the water clock but
the best replica we currently have is about five feet tall
and doesn't actually keep time
Figure 5: The Chinese Hydraulic Water clock
created by Su Song
11
THE WATER CLOCK PAGE 4
Greco-Roman world
An early 19th-century illustration of Ctesibius's (285222
BC) clepsydra from the 3rd century BC. The hour
indicator ascends as water flows in. Also, a series of gears
rotate a cylinder to correspond to the temporal hours.
In Greece, a water clock was known as a clepsydra (water
thief). The Greeks considerably advanced the water clock
by tackling the problem of the diminishing flow.
They introduced several types of the inflow
clepsydra, one of which included the earliest feedback
control system. Ctesibius invented an indicator system
typical for later clocks such as the dial and pointer.
The Roman engineer Vitruvius described early alarm
clocks, working with gongs or trumpets. A commonly
used water clock was the simple outflow clepsydra.
This small earthenware vessel had a hole in its side near
the base. In both Greek and Roman times, this type of
clepsydra was used in courts for allocating periods of
time to speakers. In important cases, when a person's life
was at stake for example, it was filled. But, for more
minor cases, it was only partially filled. If proceedings
were interrupted for any reason, such as to examine
documents, the hole in the clepsydra was stopped with
wax until the speaker was able to resume his pleading.
Figure 6: An early 19th-century illustration
In the 4th century BC, the clepsydra is known to have of Ctesibius's (285222 BC) clepsydra from the
been used as a stop-watch for imposing a time limit on 3rd century BCE. The hour indicator ascends as water
clients' visits in Athenian brothels. flows in. Also, a series of gears rotate a cylinder to
Slightly later, in the early 3rd century BCE, the correspond to the temporal hours
Hellenistic physician Herophilos employed a portable
clepsydra on his house visits in Alexandria for
measuring his patients' pulse-beats. By comparing the
rate by age group with empirically obtained data sets, he
was able to determine the intensity of the disorder.

Between 270 BCE and 500 CE, Hellenistic (Ctesibius, Hero

of Alexandria, Archimedes) and Roman horologists and
astronomers were developing more elaborate
mechanized water clocks. The added complexity was
aimed at regulating the flow and at providing fancier
displays of the passage of time.
For example, some water clocks rang bells and gongs,
while others opened doors and windows to show
figurines of people, or moved pointers, and dials.
Some even displayed astrological models of the universe.
The 3rd century BCE engineer Philo of Byzantium
referred in his works to water clocks already fitted with
an escapement mechanism, the earliest known
of its kind.
The biggest achievement of the invention of clepsydrae
during this time, however, was by Ctesibius with his
incorporation of gears and a dial indicator to
Figure 7: Al-Jazari's elephant water clock - 1206
automatically show the time as the lengths of the days
changed throughout the year, because of the temporal Medieval Islamic world
timekeeping used during his day. In the medieval Islamic world (632-1280), the use of
water clocks has its roots from Archimedes during the
Also, a Greek astronomer, Andronicus of Cyrrhus, rise of Alexandria in Egypt and continues on through
supervised the construction of his Horologion, known Byzantium. The water clocks by Persian engineer
today as the Tower of the Winds, in the Athens Al-Jazari, however, are credited for going "well beyond
marketplace (or agora) in the first half of the 1st century anything" that had preceded them.
BC. This octagonal clocktower showed scholars and In al-Jazari's 1206 treatise, he describes one of his water
shoppers both sundials and mechanical hour indicators. clocks, the elephant clock. The clock recorded the
It featured a 24-hour mechanized clepsydra and passage of temporal hours, which meant that the rate of
indicators for the eight winds from which the tower got flow had to be changed daily to match the uneven
its name, and it displayed the seasons of the year and length of days throughout the year.
astrological dates and periods.

12 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

THE WATER CLOCK PAGE 5 - END
To accomplish this, the clock had two tanks, the top tank
was connected to the time indicating mechanisms and the
bottom was connected to the flow control regulator.
Basically, at daybreak the tap was opened and water
flowed from the top tank to the bottom tank via a float
regulator that maintained a constant pressure in the
receiving tank.
Figure 8:Water-powered automatic castle clock
of Al-Jazari, 12th century.
The most sophisticated water-powered astronomical
clock was Al-Jazari's castle clock, considered by some to
be an early example of a programmable analog
computer, in 1206
It was a complex device that was about 11 feet (3.4 m)
high, and had multiple functions alongside timekeeping.
It included a display of the zodiac -
(In both astrology and historical astronomy, the zodiacis a circle
of twelve 30 divisions of celestial longitude that are centered
upon the ecliptic, the apparent path of the Sun across the
celestial sphere over the course of the year.)-
and the solar and lunar orbits, and a pointer in the shape
of the crescent moon which traveled across the top of a
gateway, moved by a hidden cart and causing automatic
doors to open, each revealing a mannequin, every hour.
It was possible to re-program the length of day and night
in order to account for the changing lengths of day and
night throughout the year, and it also featured five
musician automata who automatically play music when
moved by levers operated by a hidden camshaft attached
to a water wheel.
Other components of the castle clock included a main
reservoir with a float, a float chamber and flow regulator,
plate and valve trough, two pulleys, crescent disc
displaying the zodiac, and two falcon automata dropping
balls into vases.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
The first water clocks to employ complex segmental and
epicyclic gearing was invented earlier by the Arab
engineer Ibn Khalaf al-Muradi in Islamic Iberia c. 1000.
His water clocks were driven by water wheels, as was
also the case for several Chinese water clocks in the 11th
century. Comparable water clocks were built in
Damascus and Fez. The latter (Dar al-Magana) remains
until today and its mechanism has been reconstructed.
The first European clock to employ these complex gears
was the astronomical clock created by Giovanni de
Dondi in c. 1365.
Like the Chinese, Arab engineers at the time also
developed an escapement mechanism which they
employed in some of their water clocks.
The escapement mechanism was in the form of a
constant-head system, while heavy floats were used as
weights.
Figure 9: An incomplete scaled-down model of Jang
Yeong-sil's self-striking water clock
Korea
In 1434 during the Choson (or Joseon) Dynasty, Chang
Yongsil (or Jang Young Sil), Palace Guard
and later Chief Court Engineer, constructed the
Jagyeongnu (self-striking water clock or striking clepsydra)
for King Sejong.
What made the Jagyeongnu self-striking (or automatic)
was the use of jack-work mechanisms,
by which three wooden figures (jacks) struck objects to
signal the time.
This innovation no longer required the reliance of human
workers, known as "rooster men",
to constantly replenish it.
By 1554, the water clock spread from Korea to Japan.
Water clocks were used and improved upon throughout
Asia well into the 15th century.
13
 NEW LAZARUS VERSION 1.4 FPC 2.6.4 (PAGE 1)

starter expert

A new version of Lazarus has been

released. It's a major step in
programming with Lazarus...
The IDE has been updated very much so
here is a list of items that helps you
understand what changed

LCL Changes
Added methods and utilities to load objects from FPC resources
Changed all LCL resources from LRS to RES.
As a result they can be edited in executables using resource editors on Windows platform.
DBImage changes versus 1.2:
DbImage implements loading stream directly if it doesn't have a known header,
WriteHeader property. This makes writing image header optional improving compatibility
with Delphi controls
Translations unit: SetFuzzy (boolean with default value false) parameter was added
to TPOFile.Add method. It allows to mark PO entry as fuzzy (when true).
TDateTimePicker and TDBDateTimePicker components were added.
They are Delphi compatible and are installed by default, but have their own package
instead of being part of LCL.
TComboBoxEx and TCheckComboBox components were added.
They are Delphi compatible and are part of LCL.

IDE Interfaces Changes

Easier hint windows in IdeIntf
Unit IdeHelpIntf has a new THintWindowManager class.
In Lazarus IDE, the external renderer now is the TurboPowerIProDsgn package. This refactoring
was related to fixing a long time nasty crash bug which prevented including
TurboPowerIProDsgn by default in BigIde. Now it is included.
IDE Changes
Resources
All IDE resources are stored in RES files now.
Component images can be loaded from resources stored in RES files now.
LazRes and LrsToLfm have been improved to assist in resource migration process.
Project options has a 'Resource' section which allows to add any user resources which are
stored in the project .RES file together with project icon, manifest and version information.
Project version information was extended to allow saving build-related attribute information.
Editor
Auto-Indent now supports "tab only". If a new line is started, the indent of the previous line is
recreated using tabs. And then either spaces or cut off.
Keyword-pair/triplet highlight (matching begin,end) can be turned on/off for each pair/triplet
Keyword-pair/triplet supports if/then/else
Compiler message marks. Each compiler message shows an icon in the left gutter,
a wavy underline in the text and a mark on the right gutter.
You can right click on the left icon to get context actions, e.g. Quick Fixes.
Refactoring tool Show Abstract Methods now supports class interfaces.
Identifier completion box (Ctrl+Space) has now options to disable sorting for scope
~

=







K
If you disable both the list is sorted alphabetically.

14 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

NEW LAZARUS VERSION 1.4 FPC 2.6.4 (PAGE 2)
Debugger
Attach: List available processes (Windows/Linux/OSX only)
Debug-Inspector: Select member values (class/record/(dyn)array/pointer-deref) by double click on row
Allow single step from exception to except/finally block (includes stepping through implicit
except blocks, at then end of some methods).
Also fix single step now works, if it steps over an ignored exception.
BETA: Alternative debugger fpdebug [blog]
Designer
New Undo feature supports component moving, resizing and deleting.
Also property changed by Object Inspector can be undone.
Component palette
Palette is fully configurable. Pages can be added, pages and components can be reordered and
components can be moved between pages freely. The difference between default layout and user
layout is stored in environment options. Layouts can be exported/imported, too.
Help
The Help/Help menu starts the lhelp help viewer and shows all CHM files (if present and
configured, as done by e.g. the Windows installer)
lhelp supports diagnostic output to a log file (using e.g. --debug-log=)
Project
The target processor option (don't confuse this with the target CPU) now uses the -Cp option
instead of the -Op option. This is required by ARM processors.
The compiler in the project's compiler options is used to setup codetools. Formerly the IDE asked
the default compiler from the Tools / Options using the project's target OS and CPU.
That means you can now use build modes to switch between different compiler versions
and code navigation will use the right settings.
When target OS/CPU are not given (aka empty or default) the IDE/lazbuild now queries
the compiler for its default target platform. In other words: For cross compiling it is now enough
to select the compiler. Formerly the defaults were taken from the IDE's OS/CPU.
The IDE now parses the -Xp and -V options in the custom compiler options to find
the right compiler.
Project Option "Main unit has uses section containing all units of project":
Formerly the main source was only updated when it was enabled. Now: Only additions are
affected by this option. Renames and removes always updates the main source if it is Pascal.
Under Unix/Linux the IDE now opens always a project (lpi) in its physical path
(i.e. all symlinks are resolved). This is compatible with FPC,
which always uses the physical directory as working directory.
Project Inspector:
The Inspector now supports multi selection. For example delete multiple files or set properties.
You can drag files from other applications and drop them on Inspector to add files to the project.
You can drag files to other directories (drag the files onto a file or directory in the package editor).
New menu item: Move/copy selected files to a directory. This makes it easy to split a big
package into several sub directories.
Packages
Packages now use by default the project compiler. This comes from a change to the macro
$(CompPath), which now resolves to the project compiler.
The target processor option now uses the -Cp option instead of the -Op option.
this is required by ARM processors.
Under Unix the IDE now opens always a package (lpk) in its physical path
(i.e. all symlinks resolved). This is compatible with fpc, which always uses the
physical directory as working directory.
Package Editor:
The package editor now supports multi selection. For example delete multiple
files or set properties.
You can now copy or move files via drag and drop between package editors and
to/from project inspector.
You can drag files from other applications and drop them on package editors to add
files to the package.
You can drag files to other directories (drag the files onto a file or directory in the package editor).
New menu item: Move/copy selected files to a directory. This makes it easy to split a big
package into several sub directories.
Packages are now compiled in parallel. See:
http://wiki.freepascal.org/Lazarus_Packages#Parallel_Compilation

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 15

NEW LAZARUS VERSION 1.4 FPC 2.6.4 (PAGE 3)
Messages
This window was completely rewritten. Every tool output is now clearly separated
by a header line.
Each external tool (e.g. the compiler) now runs in a thread.
The same for the biggest part of the parser.
The IDE now passes -vbq (message ids and full file names) to the compiler.
The window can handle much bigger outputs, so you can compile with more verbosity
The IDE now knows where each message came from and what tool has created them.
For example you can see the reason why a package was compiled and the parameters via the
"About" menu item.
Switch between English and translation at any time
The fpc message parser uses the message ids, the errore.msg file and the translated error*.msg file.
The -Fr compiler option (pass custom fpc message file) on Project/Package Options / Compiler
Options / Messages was removed.
Search in Messages window
Filter for message types and urgency (hint, note, warn ...)
Choose file names styles (short, relative, full)
Change the colors in Tools / Options / Messages
when you insert/delete text in the source editor the messages are now updated in line *and*
column number.
The Compile Info window was removed because it had no maintainer.
This includes the options "Show compile dialog" and "Autoclose compile dialog".
Quick fix for fpc message "No implementation for interface method found",
shows abstract methods dialog
Miscellaneous
new IDE macros $(LazVer) and $(FPC_FULLVERSION), see
http://wiki.freepascal.org/IDE_Macros_in_paths_and_filenames
Compiling for x86-64 Linux, *BSD and Solaris now passes -Cg (Generate PIC) code to the compiler.
Use -Cg- if you don't want that.
Plugins
Leakview now supports GDB stack traces without source file names and only mangled identifiers.
TurboPowerIProDsgn is installed by default (is part of BigIde). It means all hints and info panels
have a nice HTML formatting with colors and links for sources. The package could be installed
also earlier for the same effect but there was a crash bug which prevented it from being
included by default.
EditorToolbar is installed by default (is part of BigIde). It can be hidden from View menu,
thus uninstall is not necessarily needed for anyone. Lots of bugs in EditorToolbar were fixed.
Components
TOpenGLControl: works now under Linux/QT/X

Changes affecting compatibility

LCL incompatibilities
TEditButton was rewritten.
TEditButton has been redesigned as a "grouped control".
It now inherits from a different ancestor (it is no longer derived from TCustomMaskEdit).
The new design now properly aligns and anchors.
Effects:
Derived components can no longer override (or use) all of the (protected) methods of
TCustomMaskEdit. Most of the commonly used methods have been propagated
with new names reflecting the new design e.g.:
Change -> EditChange
DblClick-> EditDblClick
When the component has focus, then checking if (ActiveControl is TButtonEdit) will be False,
since ActiveControl in this case is the internal edit control (of type TEbEdit).
(Code that checks for (ActiveControl is TCustom(Mask)Edit) will still evaluate to True.)

16
6 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
NEW LAZARUS VERSION 1.4 FPC 2.6.4 (PAGE 4 - end)
Remedy:
Use EditChange, EditDblClick etc. in derived controls.
Use (ActiveControl.Parent is TEditButton), or alternatively (ActiveControl is TEbEdit)
TControl.GetChildsRect renamed to TControl.GetChildrenRect
Effect: compile error: There is no method in an ancestor class to be overridden:
"TYourControl.GetChildsRect(Boolean): <record type>;"
Reason: Incorrect English
Remedy: use GetChildrenRect instead. TControl.GetChildsRect renamed to
TControlScrollBar.AutoCalcRange was removed
Effect: compiler error: There is no method in an ancestor class to be overridden:
"TYourControlScrollBar.AutoCalcRange;"
Reason: Code for calculating the AutoScroll ranges was moved from the two scrollbars
to the new proteced method TScrollingWinControl.CalculateAutoRanges.
This prevents an endless loop when the two scrollbars depend on each other, it simplifies
the code and reduces some overhead.
Remedy: Override TYourControl.CalculateAutoRanges instead.
TDateEdit.DialogTitle property was removed
Effect: Compile error if the property was set in code. LFM loader removes it from form files.
Reason: Unused and thus misleading and confusing.
Remedy: Remove it from your code.
TMemo, TTextStrings and TCustomStringGrid: changed behaviour of
LoadFromFile/SaveToFile
Effect: LoadFromFile/SaveToFile respectively LoadFromCSVFile/SaveToCSVFile now
take strings in UTF8-encoding (was: system encoding) as their parameter.
Reason: LCL uses UTF8 internally; consistency with e.g. TSynEdit.
Remedy: do not use Utf8ToSys() anymore in the calls to these procedures.

IDE incompatibilities
Changed parameters
LazarusIDE.DoJumpToCompilerMessage: changed Line integer to TMessageLine
CompilerOptions.ShowAllProcsOnError: was removed, option -vb is now always passed
CompilerOptions.ShowNothing: was removed, not needed
LazarusHelp.ShowHelpForMessage: removed parameter Line.
The IDE now always shows helpfor the currently selected line.
IDE Macro CompPath
Effect: IDE uses the project compiler instead of the default compiler set in the IDE options.
Reason: The macro $(CompPath) now resolves to the project compiler.
Packages are now compiled with the project compiler.
Remedy: Use $CompPath(IDE)
Old IDE does not reopen first file when opening a project
Effect: When a project saved with a new IDE (1.3+) is opened with an old IDE (e.g. 1.2),
the first file in the source editor is not reopened automatically.
Reason: The default value for Editor position is now "0", which is not stored in the lpi,
creating smaller lpi files.
Remedy: Open the file manually.
IDE does not show Compile Dialog
Effect: Compile Info window does not appear when compiling.
Options Show compile dialog and Autoclose compile dialog are missing.
Reason: The code that runs the compiler was completely rewritten. The dialog needed a
big rewrite too, but it had no maintainer.
Remedy: You can abort a compile via Run / Abort Build or its shortcut Ctrl+Alt+Shift+G.
You can change the shortcut in Tools / Options / Editor / Key Mappings.
The number of errors, warnings and hints are shown in the Messages window.
IDE/lazbuild cross compiles for different target OS/CPU
Effect: When the target OS/CPU are not set (i.e. empty or default) the 1.4 IDE/lazbuild
compile for a different target than Lazarus 1.2.
Reason: Formerly the IDE took as default its own OS/CPU. Now it queries the project's
compiler and uses its default target OS/CPU.
Remedy: Specify target OS/CPU in Project options / Compiler options or for compiling
the IDE set Tools / Configure build Lazarus.

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 17

 BY ANDREA RAIMONDI
SECURITY IN APPLICATIONS: PASSWORD HANDLING (PAGE 1)
Introduction
Have you ever had to create a registration
module with a login dialog? Of course you
have - every programmer I know of has had
to. Especially if you are a beginner, it is not
obvious what is the best way to go about
creating such a dialog. In times past you
might have got away with use of a plain text
password.
Today, though, I see tutorials which start by
explaining that plain text passwords are a
bad idea. There is a good reason for this
advice: users tend to re-use their passwords
for multiple websites/applications. So if a
username-password combination is exposed,
it could very well be useful across a number
of sites.
Convenience trumps security, again
As the section header states, convenience trumps
security every time. Users reuse account names and
passwords because it is convenient. Also, users are
not generally very good at coming up with new
passwords, let alone remembering them which
makes our job much harder. Hence, we really have
to do two things:
Ensure that the password cannot
be guessed easily
Help the user find a good password
and stick with it
Since you are the developer, it is your job to ensure
the password cannot easily be broken. Even if the
user chooses goofy as their password, it is your
job to ensure that this password takes a long time to
be discovered. It's not the user's job but your job
and yours alone. Please note that a password will
eventually be discovered, the real issue here is how
long it takes before that happens.
Make it harder on the bad guys
If you have ever built anything exposed on the
internet which needs user registration (whether a
3-tier application or a website), you will be familiar
with the concept of hashing. You will also have
been told that not all hashes are born equal and
there's a thing called a cryptographic hash. This
kind of hash function has the property that by
flipping one bit, you make the end result
completely different. This is called an avalanche
effect because it's like an avalanche, every small
difference increases over successive iterations
ultimately producing an enormous change.
If you have been involved with websites in the
past, your first port of call would've been MD5 for
this. Of course it would, because it was fast and
supposedly secure.
18
Clearly, as this preference emerged,
guess who started having a closer look at it to
check whether there were pitfalls? That's right, the
bad guys and also researchers. Someone found a
really bad hole in the function, so its use has been
discouraged over time, just as the DES became
useless as more computing power was added to
personal
The Data Encryption Standard (DES, was
computers.
once a predominant symmetric-key algorithm
for the encryption of electronic data
When researchers realised that Md5 totally
insecure, a new family of hash functions emerged
called SHA. There are several of these, some of
which have already been broken. The one regarded
most highly right now is SHA256. So that's the one
you should use in new projects.
The MD5 message-digest algorithm is a widely used
cryptographic hash function producing a 128-bit (16-byte)
hash value, typically expressed in text format as a 32 digit
hexadecimal number. MD5 has been utilized in a wide
variety of cryptographic applications, and is also commonly
used to verify data integrity.
So, is that it? Is it enough to use that and feel you
have completed your job well? Well No, because
you are doing only one iteration using it. That's not
good. You should be doing at least a hundred
iterations, using the previous output as input.
Better yet, get the previous output, encode it in
some way (say, MIME or BASE64) and then hash it
again. I know the registration and login processes
will be slower this way, but does anybody really
care? I mean, computers are very fast, even the
ones providing cheap hosting. Another second is
not going to be a noticeable problem.
So, after that, are we finished? Well No, because
your job is also to suggest to users the kind of
passwords they will need to use. To this end, I see
lots of people repeating the common clich: short
passwords are easily broken, so you should have a
minimum length limit. You have no idea how
angry I get at this bad advice. First of all, bad guys
love a minimum limit. They really do, because it
chops off an entire dataset of millions of potential
matches with lengths less than the minimum and
they can therefore optimise their search. By the
way, this is how the British broke Enigma, because
the Germans started to put limits to the frequency
of the starting and ending letters with the intent of
making the detection harder.
It backfired though, because after they put limits,
some codes started reappearing, which greatly
helped the British to break it. We really never learn
anything from history, do we?
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
SECURITY IN APPLICATIONS: PASSWORD HANDLING (PAGE 2)
The second thing is that, luckily, a good majority of
passwords input by users are 6 characters or longer.
So, why is it so easy to break them? Well, part of
this is that many website developers think they will
be smarter than the bad guys and so do not hash
their passwords. They think they can get away
simply with encryption so that the password
cannot then be recovered.
The reason this is bad is that a lot of the time
they do not just commit the cardinal sin of
encrypting them, they even use very poor
encryption methods which are vulnerable to
frequency analysis or other statistical analysis.
Again, this happens because of a desire not to delay
login times, which really should not be an issue
since login and registrations are done fairly
infrequently compared to other operations.
Frequency analysis
Frequency what? Consider this text: it is written
in English and is fairly long. If you count the letters,
you will notice that some appear more frequently
than others. Hence, if you know a text has been
written in English and you use a bad encryption
algorithm, some bytes will appear more frequently
than others. By matching the two pieces of
information, you can reasonably assume that a
certain byte corresponds to a certain letter. This is
how you break a Caesar cipher. The Vigenre
cipher is very similar, except that you have to do it
in a multi-step fashion.
Statistics
Another tool used by malicious users is statistics.
When they break a certain set of passwords, they
will update a count in their dictionaries, so they
know which are more likely to appear than others.
This is another very useful tool allowing them to
optimise away another swathe of potential
passwords. They know, for example, that if the
username is Tony there are good chances the
password could have 2 to 4 digits representing the
year of birth. All of this information is fed to their
tools to weed out bad candidates and speed up the
recovery of passwords.
You can use statistics against them,
though
Oh yes! You can and you should. Say that we have
a user Tony with password tony1957. That
password will be found in less than 2 hours,
granted. Do not even doubt that. Can we make that
password more secure without radically changing
it? Oh yes, we can. What if the password was
tony5719? Now, there are still four digits, but it's
not a year anymore and the malicious code
dealing with the year will fail, because it does not
account for that kind of thing.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
Or the password could be, more
viciously, 57tony19. It still contains exactly the
same information and it's just as easy to remember,
but it is a lot harder to guess because it does not fit
the statistical expectation. Hence, if you give this
kind of advice on your website, you can be sure
that your users will find ways to comply with your
suggestions while still remembering the password
easily. Plus, if this is the advice you keep giving,
the bad guys will have to assume that all bets are
off, and they do not like that.
The password you hash does not have
to be the same one as was entered
If the previous section made you think, this will
make you think even more. Why on Earth should
you be using the same password they give you to
hash? Just use another one, derived from that. This
is called password mangling and it can be as
simple as counting the characters of a string and
ordering them by frequency. So let's say the
password is tony1957: you will end up with
1t1o1n1y11191517. Now, that's a password! See?
Even with a bad password, you still can get a
good password. And good luck with the statistics
on that! If you want to be particularly devious, you
can have a password strength evaluator which
highlights the bad passwords leaving the good
ones alone. Also, along with this, you can also use
some padding characters, which will be part of the
string being hashed and the malicious user will be
left wondering whether the user or the system
inputted them, making the password ultimately
useless.
When the going gets tough, the tough
get going
If you feel that the above is only a good start, you
can also go overboard and be really mean. One of
the techniques I devised (but never found a reason
to use, because I don't deal with stuff requiring this
level of security) is the multi-password: who says
that you always have to use the same password
field? Why can't you use one, say, from Monday to
Wednesday and another, with a different hash, from
Thursday to Sunday?
When the cracker downloads the MySQL dump
he'll find out there are two password fields hang
on, is the password split in two fields or are they
different encodings of the same password?
But I would only use this if I wanted to make the
poor malicious user cry really hard.
How nasty you are is only up to you
I am sure that I have now inspired you to think of
ideas that can work, provided that you make a plan
and discuss it with both your peers and your
seniors, because it's easy to get these things wrong
19
SECURITY IN APPLICATIONS: PASSWORD HANDLING (PAGE 3)
and do something stupid instead of clever. What I
am suggesting here is not that you should not be
clever, I am suggesting that you should be clever in
things that do not affect the cryptographic
properties of the hash and that is where people
usually get it wrong because they try to be cleverer
than the researchers that do this for a living. News
flash: you are not.
Not all passwords can be hashed
If your password cannot be hashed, you are in
trouble. What do you mean some password can't be
hashed? Well, for example, say that you have to
automatically log in to a site and need to save the
credentials: that account needs to be saved
somewhere because you need it for the function to
work. This is one of those cases where, as a
developer, you have to assert security over
convenience: you simply do not store them. You
ask them every time. There is no other secure way,
because malicious users can't reach what you do
not store. If you have an E-Commerce website and
you store credit card numbers, you should stop.
Just don't. You are not PayPal and will never be:
stop being delusional. With an ever increasing
number of bad attacks on really well known
websites, it is dawning on users that convenience
sometimes is a bad thing. We are not yet where we
should be, but the time will come when they realise
it and will start requesting it. If you were able to
explain why you made this choice, they will
certainly trust you more than the other guy who
says they can store their credit card number
securely.
You have to give up features you cannot
implement
Obviously, the choice of not storing some
passwords comes at the expense of features that
would of course be possible if you did. It takes a lot
of guts and courage to stand up and say We can't
do this because it is dangerous for our users and
eventually our reputation when we get hacked but
it has to be done sometimes. But what if you are
told to go on and save the data anyway?
If you really, really, really have to, there are some
things you can actually do
These are suggestions that you should only use if
you are being ordered to do this and if you have no
other choice. For a start, do not save them in the
database. If the cracker gets in and gets a dump, he
or she will go straight to the accounts table and try
to get the passwords encrypted there, only to find
out they actually aren't there at all.
20
Darn! Save them in encrypted files on
another machine and only make them accessible
through a script which only accepts requests from
the machine where your website is located and
possibly use a really long and nasty password in
the script to decrypt them.
What if we didn't need passwords at all?
We have been discussing passwords, but really do
we really need them? Have you ever heard of
alternatives to passwords? And I am not talking
about biometric stuff. That does not work unless it's
done properly, which means with devices that cost
thousands of dollars, specific usage protocols and
trained personnel. What I am talking about is the
use of images. Say that you are creating a website
and that you have 1 or 2 million small images on
the server. Now, say that when you register a user,
you show 10 of those images and save which ones
you were showing on the user profile. Now, let's
also say that you associate each image to a piece of
text which defies statistics and then allow the user
to pick 4 out of 10 in a certain order. They have to
use that order again when they log in. I argue that
in such a case, if the images shown are truly
random, you might not even really need a
username because the chances that two users get
the same image set and pick the same 4 in the same
order are minimal. The system is also easy to
expand if needed by simply adding new images.
They do not even need to be really big, I'd say that
a 1000x1000 pixel image should be more than
enough, therefore limiting the amount of hard disk
space needed.
Creating of a password:
Alan Turing June 23, 1912
AlanTuring 23 6 1912
23 Alan 6 Turing 1912
@23Alan6TuringMCMXII
@23Alan6TuringMcmX2!
@23A6TMcmX2!
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
SECURITY IN APPLICATIONS: PASSWORD HANDLING (PAGE 4)
Conclusion
To sum up: security is really about options and trade-
offs. If you decide to do something,
then you need to know the consequences of your
actions at all times. This is how you make considered
decisions. I know that some of the above suggestions
may sound extreme, or crazy but sometimes being
creative helps in making problems easier, or removes
them altogether.
For instance, take the suggestion made above that
you move your encrypted profile information to another
machine. Imagine a cracker or black-hat who takes the
time to break into the machine, only to find out that the
data he is looking for is not actually there, and he has
to do it all over again. And then maybe he or she does
and finds that he has to copy a large swathe of files
and, when done, he or she will have to decrypt them
one by one because, of course, a binary append just
doesn't work. How do you think he or she will feel?
Yeah, the malicious user may eventually break into
your data. He or she might actually decrypt all of them.
But the time wasted on it won't be recovered. Even if
using a bunch of machines in the cloud, the time spent
is not recouped. And then he or she must be lucky and
the profiles must be worth it. You understand what I
mean there,
don't you?
better office benelux | asterlaan 6 5582EH waalre | 040 222 26 43 gtan@better-office.com
On the other hand, if you are just doing a
to-do list, do you really need high security? Probably
not, so maybe it is just worth using a good hash and
go with that. It all boils down to what you, your
employer or your customers stand to lose.
That is where you should draw the line:
passwords will be broken, files will be decrypted. A
determined individual will eventually get his or her
hands on what he or she should not.
What matters, though, is the amount of time taken to
do so. If the servers are properly monitored,
if it takes the attacker a week to decrypt the data,
then that data will most likely be useless,
because the breach will have been detected and
communicated to customers. That is what you can do
and there's not much else that matters really.
The Internet is a nasty place, there's nowhere to hide
and you can simply go with the flow but be smart
about it.
About the author:
Andrea Raimondi,
born 1977.
Started programming at ripe old age of 14.
Professionally started in 2000.
Currently consulting with a multinational
company.
Has a great passion for security and how to
outsmart the scum that trawls through the
interwebs. andrea.raimondi@gmail.com
What is Visuino?
Visuino is the latest innovative software from Mitov Software. A visual programming
environment allowing you to program your Arduino boards. Although it currently
supports the official Arduino boards, it is not restricted to their support alone and
requests to support new hardware are welcome.

INTRODUCTION What is Arduino?

The components found in the Visuino software represent their hardware components and you
will easily be able to create and design your programs using drag and drop. No equipment or
hardware is needed to run the software in design mode. Once you have completed the design,
you can connect Arduino board upload and run it.

For those people who are not strong on writing code then designing, compiling and creating
Arduino programs has never been easier! Why waste time on creating code when we have done
all the hard work for you already? You have your Arduino board, and great hardware design,
see it running in minutes, not hours!

Currently we are running a Beta program which you can be part of by joining our Google group.
Join the group now to download and test the software or send an email to mitov@mitov.com.

IN THE NEXT ISSUE:

ALL ABOUT VISUINO

www.visuino.com

VISUINO IS THE LATEST INNOVATIVE PRODUCT

FROM MITOV SOFTWARE.
 IN REMEMBRANCE OF OF ALAN TURING
Alan Turing was a genius who might have saved
the world....
Founder of computer science, mathematician,
philosopher, codebreaker, visionary and a gay man
before his time:
Here is the statement of apology by the
Prime Minister, Gordon Brown,
10 September 2009: 60 years to late
... a brilliant mathematician... whose unique
contribution helped to turn the tide of war...
horrifying that he was treated so inhumanely...

1912 (23 June): Birth, Paddington, London

1926-31: Sherborne School
1930: Death of friend Christopher Morcom
1931-34: Undergraduate at King's College, Cambridge University
1932-35: Quantum mechanics, probability, logic. Fellow of
King's College, Cambridge
1936: The Turing machine, computability, universal machine
1936-38: Princeton University. Ph.D. Logic, algebra, number theory
1938-39: Return to Cambridge. Introduced to German Enigma
cipher machine
1939-40: The Bombe, machine for Enigma decryption
1939-42: Breaking of U-boat Enigma, saving battle of the Atlantic
1943-45: Chief Anglo-American crypto consultant. Electronic work.
1945: National Physical Laboratory, London
1946: Computer and software design leading the world.
1947-48: Programming, neural nets, and artificial intelligence
1948: Manchester University, first serious mathematical use
of a computer
1950: The Turing Test for machine intelligence
1951: Elected FRS. Non-linear theory of biological growth
1952: Arrested as a homosexual, loss of security clearance
1953-54: Unfinished work in biology and physics
1954 (7 June): Death (suicide) by cyanide poisoning,
Wilmslow, Cheshire.

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 23

INFORMATION ABOUT: ENIGMA STEALING SECRETS
Arthur Scherbius, a German engineer,
developed his 'Enigma' machine, capable of
transcribing coded information, in the hope of
interesting commercial companies in secure
communications. In 1923 he set up his
Chiffriermaschinen Aktiengesellschaft
(Cipher Machines Corporation) in Berlin to
manufacture his product. Within three years the
German navy was producing its own version,
followed by the army in 1928 and the air force in
1933.
Enigma allowed an operator to type in a
message, then scramble it by using three to five
notched wheels, or rotors, which displayed
different letters of the alphabet. The receiver
needed to know the exact settings of these rotors
in order to reconstitute the coded text. Over the
years the basic machine became more
complicated as German code experts added plugs
with electronic circuits.
Britain and her allies first understood the
problems posed by this machine in 1931, when
Hans Thilo Schmidt, a German spy, allowed his
French spymasters to photograph stolen Enigma
operating manuals. Initially, however, neither
French nor British cryptanalysts could make
headway in breaking the Enigma cipher.
It was only after they had handed over details to
the Polish Cipher Bureau that progress was made.
Helped by its closer links to the German
engineering industry, the Poles managed to
reconstruct an Enigma machine, complete with
internal wiring, to read the German forces
messages between 1933 and 1938.
Ultra intelligence
With German invasion imminent in 1939, the
Poles opted to share their secrets with the British,
and Britain's Government Code and Cipher School
(GC&CS) at Bletchley Park, Buckinghamshire,
became the centre for Allied efforts to keep up
with dramatic war-induced changes in Enigma
output.
Top mathematicians and general problem-solvers
were recruited and a bank of early computers,
known as 'bombes', was built to work out the
Enigmas vast number of settings.
The Germans were convinced that Enigma output
could not be broken, so they used the machine
for all sorts of communications on the battlefield,
at sea, in the sky and, significantly, within its
secret services. The British described any
intelligence gained from Enigma as 'Ultra', and
considered it top secret.
Only a select few commanders were made aware
of the full significance of Ultra, and used it
sparingly to prevent the Germans realising their
ciphers had been broken.
By Andrew Lycett
24
An Enigma machine was any of
several electro-mechanical rotor
cipher machines used in the
twentieth century for
enciphering and deciphering
secret messages.
Enigma was invented by
the German engineer
Arthur Scherbius
at the end of World War
I. Early models were
used commercially
from the early 1920s,
and adopted by military
and government services of
several countries, most notably Nazi Germany
before and during World War II. Several different
Enigma models were produced, but the German
military models are the most commonly
recognised.
German military messages enciphered on the
Enigma machine were first broken by the Polish
Cipher Bureau, beginning in December 1932.
This success was a result of efforts by three
Polish cryptologists, Marian Rejewski, Jerzy
Rycki and Henryk Zygalski, working for Polish
military intelligence. Rejewski reverse-
engineered the device, using theoretical
mathematics and material supplied by French
military intelligence. Subsequently the three
mathematicians designed mechanical devices for
breaking Enigma ciphers, including the
cryptologic bomb.
From 1938 onwards, additional complexity was
repeatedly added to the Enigma machines,
making decryption more difficult and requiring
further equipment and personnelmore than the
Poles could readily produce.
On 25 July 1939, in Warsaw, the Poles initiated
French and British military intelligence
representatives into their Enigma-decryption
techniques and equipment, including Zygalski
sheets and the cryptologic bomb, and
promised each delegation a Polish-reconstructed
Enigma. The demonstration represented a vital
basis for the later British continuation and effort.
During the war, British cryptologists decrypted a
vast number of messages enciphered on Enigma.
The intelligence gleaned from this source,
codenamed "Ultra" by the British, was a
substantial aid to the Allied war effort.
Though Enigma had some cryptographic
weaknesses, in practice it was German
procedural flaws, operator mistakes, failure to
systematically introduce changes in
encipherment procedures, and Allied capture of
key tables and hardware that, during the war,
enabled Allied cryptologists to succeed.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
LAZARUS NOW CAN USE GOOGLE APIS
starter expert Version 1.4
FP 2.6.4 and up
REST CLIENTS: USING THE
GOOGLE APIS IN FREE PASCAL
CREATED AND WRITTEN BY
MICHAL VAN CANNEYT.
ABSTRACT
This article demonstrates how you can use
the Google APIs to access Google's services.
Using the Google APIs presumes use of
OAuth 2, and the use of REST technologies.
The article also shows you how to create
your own Google API in Pascal using the
Google Discovery service.
1 INTRODUCTION
More and more, applications are connected to the
Web or implemented solely on the web (Facebook,
twitter). Data is fetched from and stored in the web,
even for traditionally desktop oriented software
such as spreadsheets or word-processing software.
Google docs (or Apps) and more recently Microsoft
Office365 are prime examples of this. You could
even say that these web APIs have become as
important as the traditional OS and installed
software APIs: Software running on tablets and
Figure 1: The Google APIs component palette
Figure 2: The google drive demo program
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
PAGE 1
smartphones is expected to interact
with online services. To be able to
interact with these web applications and
this data, APIs are needed. This is increasingly
done using REST technologies. (REST stands for
Representational State Transfer). REST is not a
protocol, rather an architectural way to make data
available on the web. It rests on 2 pillars:
1. Everything is a resource, accessible through
a URI (In computing, a uniform resource
dentifier (URI) is a string of characters used to
identify a name of a resource.) - which almost
implies use of the HTTP protocol. In database
terms one could say that every record of a
table is accessible through its own URI.
2. Data manipulation follows mostly the CRUD
(Create Read Update Delete) pattern, much as
data in a database. These operations translate
nicely to the HTTP verbs POST, GET, PUT
and DELETE.
Since all this is very much the technology used in
web browsers, it is easy to understand and use.
The downside of being an architecture is that there
is no strict protocol, so each application developer
can develop his own protocol Where XML was the
format of choice for messages in SOAP-related
APIs, for REST APIs this has been replaced
mostlywith data descriptions in JSON format
25
LAZARUS NOW CAN USE GOOGLE APIS PAGE 2
(JavaScript Object Notation), which has several
advantages over XML: it is less verbose (that applies
to the specification as well: the JSON specification fits on
an A4 page), it is less sensitive to whitespace, and it
has some native notion of data types (including
string, boolean, number, object, and array). Last but not
least, it is a subset of Javascript, and as such can be
handled natively by any browser.
Obviously all the data on the web needs to be
protected from unauthorized access. This protection
is increasingly done using OAuth (version 2). (OAuth
is an open standard for authorization. OAuth provides
client applications a 'secure delegated access' to
server resources on behalf of a resource owner. It specifies
a process for resource owners to authorize third-party
access to their server resources without sharing their
credentials.
OAuth is also implemented using JSON. OAuth in
essence relies on the user giving consent to an
application (mostly the browser) to use data on his or
her behalf.
All the technologies needed to perform REST
operations and OAuth authorization are available in
Free Pascal. It was therefore only a matter of time
before a comprehensive set of components became
available to easily access web APIs. In this article
we'll describe how to access the Google APIs using
REST in Free Pascal and Lazarus, and demonstrate
how they can be used in sample applications such
as the Google Drive demo (figure 2)
Access to Microsoft Office365 is also
being worked on, but will be the subject
of a later article.
2 Architecture
The Free Pascal implementation of the web APIs
makes several assumptions:
1. Transport uses the HTTP(s) protocol.
Several TCP/IP socket implementations are
available (including Synapse, lnet, Indy, the FPC
native client). Each developer has his own
preferred implementation which he uses.
So, the REST APIs should work with each of
those. That means that the HTTP request and
response mechanism has been abstracted into
a new class called TFPWebClient. Concrete
implementations of this abstract class have been
made for Synapse and TFPHTTPClient.
2. Authentication of the HTTP requests happens
using OAuth2, but other mechanisms can be
implemented as well. Since the Oauth2
protocol involves exchanging tokens with a
webserver, it needs a HTTPS transport layer
as well.
26
3. Serialization of objects is done using
JSON. Therefore the basic REST object
contains a JSON serialization
mechanism, based on RTTI.
The upshot of these architectural decisions is
that there are several classes involved in the
REST implementation:
TFPWebclient
handles HTTP(S) messages.
A descendent of this client is needed, which uses a
particular TCP/IP suite to actually send the request
and read the response.
A request is represented by a TWebRequest class,
the response will come in the form of a
TWebResponse class.
Requests are executed using the ExecuteRequest
and ExecuteSignedRequest methods: To each
TFPWebclient instance, a TRequestSigner
component can be attached. This component is
allowed to examine the request and response when
they are sent or received, allowing a request to be
signed (for instance by adding an Authorization header
with a Bearer token).
TFPOauth2Handler
is a class that handles OAuth 2 authentication.
Technically, it is a descendent of a
TRequestSigner that will add the OAuth2
header. This class may use the TFPWebclient
instance (or a second TFPWebclient instance) to
execute token exchange requests as part of the
OAuth2 flow.
The class can be used in offline mode (for desktop
apps) as well as in online mode (for web applications).
TRestObject
This is the basic object that represents a
REST resource. It has 2 important methods:
LoadFromJSON and SaveToJSON. These methods
use the RTTI to create a JSON representation of the
object, or to read the object properties from a JSON
representation. It also has a mechanism to record
which properties have been changed.
We need a mechanism to record property changes
is needed because many REST APIs allow both PUT
and PATCH (or UPDATE) methods. A PUT method
generally completely replaces a resource with the
new value specified in the request, whereas
PATCH modifies the resource by applying the
changes in the request to the existing resource.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
LAZARUS NOW CAN USE GOOGLE APIS PAGE 3
To be able to support PATCH-like functionality,
a mechanism is needed to record which properties
have changed, and to send only these properties in
a request. This mechanism is implemented using
the property Index mechanism. Each property has
a unique index, and a property setter which
accepts this index (the property getter may or may not
use this index). When the property is set, the index
is used to record the change. Since the index is
unique, the RTTI can then be used to construct a
list of property names that were modified.
Armed with these objects, a REST API client can be
made: all that needs to be done is create
descendents of TRestObject, and load them
from a HTTP response.". To modify data on the
REST server, the object's properties are set, and the
object serialized to JSON. This JSON is then sent to
the server (with using the appropriate HTTP method) .
That is basically it.
3 Service descriptions
Google has more than 100 APIs, each of which has
more than 1 resource, containing many data
structures which can be manipulated. To write
objects and serialization code for each of these
resources would be a very tedious task indeed.
Luckily, this is not necessary. Google offers a
Google Service Discovery service, which returns a
JSON document that completely describes each of
its rest-based APIs. The Google Discovery Service
is described at
https://developers.Google.com
/discovery/
The service consists of 2 parts: it lists the services
offered by Google, and it offers a description of the
REST API for each of these services. For people
acquainted with SOAP implementations: this
description is equivalent to the WSDL description
document. It is based on a JSON schema:
http://json-schema.org/
The REST API description also contains
information on the authorizations needed to use
the resources in the APIs (the so-called authorization
scope). It is very important to be aware of these
scopes: the user of the API will be asked for
consent based on these scopes. More on this below.
The Microsoft REST APIs are based on their
OData specification, and OData based services
have a similar document (the service document),
based on EDMX, (An .edmx file is an XML file that
defines a model that can be used with Entity
Framework. The model is made up of a conceptual
model, a storage model, and the mapping between these
models. An .edmx file also contains information that is
used by the EF Designer to render a model graphically.)
described at: https://www.odata.org/
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
Unfortunately, the EDMX description
is still in XML (somewhat awkward if
the JSON format is to be used) and not
as complete as the Google-provided
descriptions, implying that always a certain (very
small) amount of manual interpretation is always
required.
Converters for these two formats have been
implemented in FPC: The Google Service Discovery
REST description document can be converted
automatically to a complete Object Pascal
implementation of a client for the REST APIs.
There are two programs available to do this:
A command-line program which can be used to
convert a single API to an Object Pascal unit.
The REST description can be a file with the
JSON description of the service, or the
program can download a service description
from the Google Service Discovery server.
A GUI program that allows you to browse and
search the Google APIs and convert a selected
API to an Object Pascal unit.
The Google service discovery itself is a REST
API. So, an Object Pascal implementation can
be generated for it, using the command-line
program. This has been done, and the Google
discovery program was constructed using
this unit.
The code to convert a Google REST API
description to an Object pascal unit is a component
(TDiscoveryJSONToPas), which can be descended
from and modified if need be. If the choices made
by the author for the generated code are not to your
particular liking, the code can easily be modified to
generate different code. It has 3 important methods:
LoadFromStream This method can be used to
load a REST service description from a stream
containing valid JSON. There are 2 auxiliary
methods LoadFromFile and LoadFromJSON to
make life easier.
SaveToStream Calling this will generate
the Pascal code, and save the resulting code to a
stream. The SaveToFile method will do the same
but save directly to file, and will set the unit name if
it was not yet set.
27
LAZARUS NOW CAN USE GOOGLE APIS PAGE 4
Execute
can be used to generate the code. The
code is then available in the Source property.
There are some properties that can be used to
control the code: the parent class name for the
generated resource classes, the unit name to
generate, the depth of code indentation can be set
and so forth. The component can be found in the
googlediscoverytopas unit. A similar
component was made to convert the Microsoft
OData service discriptions to Pascal code.
A small command-line program (googleapiconv)
is available that can be used to generate a Pascal
source file from a service description file. It can also
fetch the description from the Google Discovery
service, based on the name (and version) of the
service, or simply by providing a URL.
For example, the following command will generate
a unit for the Google calendar API :
googleapiconv -s calendar/v3 -o
calendar.pp
The same unit can also be generated using this
command:
googleapiconv -u
http://www.googleapis.com/discovery/
v1/apis/calendar/v3/rest -o
calendar.pp
4 A service description breakdown
Since the Google Discovery service is a service,
there is a description of itself in the Google
Discovery service. Therefore, the command-line
program was used to create a unit
googlediscovery which implements the Google
Discovery service API. A Google API breaks down
into 4 parts, all of which have a base class in the
googleservice unit:
TGoogleClient
This is a simple component that handles the
transport and authorization. It uses a
TFPWebClient and a TFPOauth2Handler
to communicate with Google servers.
TGoogleAPI
There is a descendant of this component for
each Google service API, which handles all
calls to the service. It uses a TGoogleClient
component to handle actual communication.
The code generator creates a descendant of this
class in the unit it creates for the service.
For the Google Discovery service, the class is
called TDiscoveryAPI. This class contains
some class methods that expose metadata
about the service. You can find out the base
URL for the service, what authorization scopes
are used, where documentation and icons are
28
for this service can be found etc.
This class contains a method called
ServiceCall which is used by all
resources in the API to execute service
requests. It will use the client to do the actual
HTTP request.
TGoogleResource
For each resource exposed by the service,
a descendant of this class is generated that has
all the methods for that resource, as described
in the REST service description.
TGoogleResource uses an instance of the
TGoogleAPI class to handle all calls to the
service. For the Discovery API, there is a single
resource class TApisResource.
TGoogleBaseObject
For each data type used in the API,
a descendant of this class is used: it is a
descendant of TBaseObject and handles
loading from and saving to JSON. For the
Discovery service, there are 2 main datatypes
that descend from this base class:
TDirectoryList for the list of services, and
TRestDescription which describes a
REST API. The latter is used to create a
Pascal unit.
The JSON serialization mechanism works with an
object factory. When it needs to create an object of a
certain type (the 'kind' in Google parlance), it looks
in the factory to see which class must actually be
created. The TGoogleAPI object will register all the
classes it uses in the factory. It is possible to
override the classes in the factory, so that when a
class is requested a descendant of the class can be
returned.
For instance, the TDirectoryList is registered
with name discovery#directoryList. To
have the API return a TMyDirectoryList item
whenever it requires a discovery#directoryList
instance, the TMyDirectoryList can simply be
registered with the same name:
TMyDirectoryList.RegisterObject;
The class must override the RestKindName class
method for this to work correctly:
Function TMyDirectoryList.RestKindName: string;
begin
Result:='discovery#directoryList';
end;
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
 LAZARUS NOW CAN USE GOOGLE APIS PAGE 5

The advantage is that this mechanism allows the Then an instance of the Discovery API
programmer to create descendants of the classes in is created, and connected to the client
an API which have customised behaviour and component. The last 2 lines handle
properties, rather than modify the service initialization of the code generator, and update
description unit. When data arrives from the the caption of the Google API. In general the above
server, all private classes will be instantiated mechanism will be the same for all applications that
instead of the declared stock classes. want to communicate with a Google service API.
When the service changes, the API converter The TApisResource class represents the resources
can then regenerate the service description unit, exposed by the discovery API, and was generated
and not all customizations are not all lost. If the by the code generator as follows:
object factory does not contain TApisResource = Class(TGoogleResource)
a definition for a certain class, Public
the serializer will always fall Class Function ResourceName : String; override;
Class Function DefaultAPI : TGoogleAPIClass; override;
back to instantiating an instance
Function GetRest(_api: string; version: string) : TRestDescription;
of the declared property type. Function List(AQuery : string = '') : TDirectoryList;
Function List(AQuery : TApislistOptions) : TDirectoryList;
end;

5 Using the generated APIs
Armed with these base classes, it is time to start
using them to create an actual program.
The Google discovery demo program uses the
googlediscovery unit to create a small GUI
program. Using this GUI program the following
actions can be performed:
View and search in available services.
Open the documentation of a service
in a browser.
View the JSON rest description of the service.
Generate a unit based on the REST description
of a service.
The main form of the application simply shows a
list of services, with a button to (re)fetch the list, generated by the code generator, and this is a
and a textbox to filter the list.
The OnCreate event is used to set up everything up: description document describes for each call what
procedure TMainForm.FormCreate(Sender: TObject);
begin // set up communication.
FClient:=TGoogleClient.Create(Self);
FClient.WebClient:=TSynapseWebClient.Create(Self);
// Register all classes so they can be streamed.
TDiscoveryAPI.RegisterAPIResources;
// create the API and hook it up to the Google client. record is declared that contains each parameter as a
FDiscoveryAPI:=TDiscoveryAPI.Create(Self);
FDiscoveryAPI.GoogleClient:=FClient;
// The code generator uses its own objects.
TDiscoveryJSONToPas.RegisterAllObjects;
UpdateCaption;
end;
The first 2 methods are for the
API's internal bookkeeping for the
factory methods. The interesting
methods are List and GetRest:
The latter requires the name and
the version of the API, and will
return a description of the REST API in the
TRestDescription instance. These 2 parameters
are required and are encoded in the path of the URI
used to access the resource: this is a feature of the
API and is reflected in the signature of the methods
generated by the API.
As seen in the declaration, the List method of
this resource comes in 2 forms: One accepts a string,
the other a structure of type TApislistOptions.
This pattern can be seen in all resource classes
design choice: for each call the Google REST
optional parameters the call accepts, and usually
these parameters serve to filter the returned
response. These parameters are passed to the API in
the query variables encoded in the URL.
This is always translated by the code generator
into 2 calls: rather than creating a method that
contains all the parameters in its signature, a
field. For the List method, these parameters are
described in TApisListOptions:
TApisListOptions = Record
_name : string;
preferred : boolean;
end;

The first 2 lines set up the communication: in the

example code, the Synapse descendant of the
TFPWebClient class is used to handle transport.
To be able to stream all objects in the discovery
API, all resources needed for the API are registered.

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 29

 LAZARUS NOW CAN USE GOOGLE APIS PAGE 6

Since the API can change and to allow for custom user. Note that the base classes
queries, whenever there are such optional used in the APIs will always free
parameters for a method, the method is generated properties of class or dynamic array type
twice. The second form just accepts a query stringwhen they are destroyed: the user does not
which is passed on as-is in the URL (which means need to do this, but you do need to be aware of it.
it must be URL-encoded). Internally, the method The ShowDiscovery method
using the record just constructs the query from shows all services in the list. It has two
non-empty fields in the record, and calls the latter
arguments that can be used to filter the list:
method. PreferredOnly and a filter on text (the title,
So how can we use the TApisResource and its name, description and labels are filtered on this text).
methods ? Google APIs come in different versions, and one of
Each API class has methods to create the resource these versions is the preferred version. Normally
instances used in the API. For the discovery API, this is the version that should be used in new
there is only 1 resource, so the number of methodsimplementations. To cater for this, the demo
is limited: program has a check menu
TDiscoveryAPI = Class(TGoogleAPI) which can be used to show
//Add create function for resources only the preferred versions
Function CreateApisResource(AOwner : TComponent) : TApisResource;
Function CreateApisResource : TApisResource; of an API.
//Add default on-demand instances for resources
Property ApisResource : TApisResource Read GetApisInstance;
end;

The CreateApisResource call will

create an instance of TApisResource,
The ShowDiscovery method just fills a listview
and hooks it up to itself, so the resource
with the result of the call:
can execute service calls. Optionally, an
owner for the resource can be specified (if procedure TMainForm.ShowDiscovery(PreferredOnly : Boolean;
none is specified, the API instance is the FilterOn : String);
Var DLI : TDirectoryListitems; LI : TListItem;
owner). When the ApisResource begin
property is read, it will create an instance FilterOn:=LowerCase(Filteron);
of TApisResource if need be, and keep it LVServices.Items.BeginUpdate;
try
in memory till the API is freed.
LVServices.Items.Clear;
The same pattern is reused in all the API LVServices.Column[1].Visible:=Not PreferredOnly;
classes generated by the API code For DLI in FDirectory.Items do
generator. if ShowItem(DLI) then
begin
In the demo application, when the Refresh
LI:=LVServices.Items.Add;
button or menu item is chosen, the list of LI.Caption:=DLI.name;
available API's is fetched and displayed. LI.Data:=DLI;
This happens using the List method of the With LI.SubItems,DLI do
TApisResource. begin
Add(BoolToStr(preferred,'True','False'));
procedure TMainForm.DoFetch;
begin Add(id);
// Free any previous list. Add(title);
FreeAndNil(FDirectory); Add(version);
// Get the new list using a default ApisResource. Add(description);
FDirectory:=FDiscoveryAPI.ApisResource.List(); Add(discoveryLink);
ShowDiscovery(MIPreferredOnly.Checked,EFilter.Text); Add(discoveryRestUrl);
end; Add(documentationLink);
Add(icons.x16);
Add(icons.x32);
The second line of code gets the list of Add(DoComma(labels));
end;
services. For this, it uses the default end;
ApisResource property of the UpdateCaption;
TAPIDiscovery instance. The first line finally
LVServices.Items.EndUpdate;
cleared any previous list. The result of any
end;
API methods needs to be freed by the end;

30 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

 LAZARUS NOW CAN USE GOOGLE APIS PAGE 7

The call to ShowItem decides whether an 6 Setting up OAuth 2 on Google

item must be shown or not, depending
on the options to ShowDiscovery.
The rest of the program uses the properties
of the TDirectoryListitems: the instances
are stored in the Data property of the listitems in
the listview. For instance, to show the
documentation of a particular API,
Class Function
the following code is used: Class Function
The Google discovery service is publicly
available. This means that anyone can call
these services, no authentication or authorization
is required. Most other services, how- ever, do
need authorization to be used. The Google API
converter overrides 2 method of TGoogleAPI:
APIAuthScopes : TScopeInfoArray;virtual; abstract;
APINeedsAuth : Boolean ;virtual;

function TMainForm.CurrentAPI: TDirectoryListitems; The first method, APIAuthScopes lists the

begin scopes for which authentication can be re-
If Assigned(LVServices.Selected) quested when an API is used. The second
and Assigned(LVServices.Selected.Data)
then method, APINeedsAuth, returns True if
Result:=TDirectoryListitems(LVServices.Selected.Data) the API needs authorization.
else (this is the case when the APIauthscopes
Result:=Nil;
array is non- empty).
end;
The ServiceCall method of the
procedure TMainForm.AViewHelpExecute(Sender: TObject); TGoogleAPI class uses this function to
begin decide whether it must make a signed or
OpenURL(CurrentAPI.DocumentationLink);
end;
unsigned request. For the Google
Discovery service, the APINeedsAuth
returns False.
Things can hardly get more simple than this.
Setting up OAuth 2 for an application
To view the JSON description of a service, the
requires several steps:
following code is used:
1. The developer needs a Google account.
procedure TMainForm.APreViewRestExecute(Sender: TObject); 2. In the Google developer console,
Var DLI : TDirectoryListitems; the application must be registered.
begin
DLI:=CurrentAPI; The Google developer console is
ViewRestAPI(DLI.Name,DLI.DiscoveryRestUrl); available at:
end; https://
console.developers.google.com/project
procedure TMainForm.ViewRestAPI(const AName, AURL: String); The console currently looks like figure 4
Var S : TMemoryStream; on the next page 31, where one
begin application is defined.
S:=TMemoryStream.Create;
try 3. When the application is defined, access
if HttpGetBinary(AURL,S) then to Google APIs must be set up. This is
begin done under the APIs and Auth - APIs
ViewFile(S,sJSON,'REST discovery for '+AName);
section of the console. The programmer
S:=Nil;
end; needs to declare to Google which APIs
finally his application will use.
S.Free; https://console.developers.google.com
end; /project
end; If this is not done correctly, then any
calls to an API will fail, even if the
authorized user has given consent that
The HttpGetBinary call is a part the application may do so.
of the Synapse TCP/IP suite, and the ViewFile
call just shows a When authorizing, the Google
secondary form with a syntax highlighter. authentication service will present a consent
The other functions of the program are simple screen, which will list all actions that an
variations on these calls, the code for it will not be application is allowed to perform on behalf
presented here. of the user. The list of actions reflects what
The program can be seen in action in on page 31 APIs the programmer has selected here.
Figure 3: The Google Service Discovery demo The API selection is shown in figure 5 on
page 35.

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 31

LAZARUS NOW CAN USE GOOGLE APIS PAGE 8
4. As a last step, a pair of keys must be generated
for the application. This is done under the
APIs and Auth - Credentials section of the
console. One key is a unique identifier for the
application (the client ID), the other is a secret
key (a password). These are used when asking
for user consent: they are sent to the Google
authorization server when the application
needs permission to fetch data from a user.
Through the OAuth 2 protocol flow,
the application will then end up with a new
token (the access token) that it will use to ask
permissions to acces data on behalf
of the user.
The credentials configuration is shown in
figure 6 on page 36. Depending on what kind
of application you are developing, different
settings must be used.
For desktop applications, the 'native
client application' type must be chosen,
and urn:ietf:wg:oauth:2.0:oob
or http://localhost must be chosen
as the Redirect URI.
In the Google Developer Console a new Client
ID and Client Secret can then be generated.
The client ID and Secret must be used in the code
of your application - preferably scrambled
somehow. Google offers a JSON download of this
data, the contents of this file must be kept secret.
If this data becomes public, then another
programmer can impersonate your application and
start downloading or, worse, wreak havoc on the
user's data (and you will get the blame for it).
The second method, APINeedsAuth, returns True
if the API needs authorization. (This is the case when
the APIauthscopes array is non-empty).
Figure 3: The Google Service Discovery demo
Figure 4: Defining an application in Google
LAZARUS NOW CAN USE GOOGLE APIS PAGE 9
Figure 5: Selecting APIs for the application in Google
7 Setting up OAuth 2 in the application
Once the server part was set up, the application
part can be configured. To demonstrate this, the
Google Calendar demo program is used. It
makes use of the googlecalendar unit, generated
with the API code generator. The calendar demo
shows a list of the user's calendars of the user, end;
and allows the user to view the items in the
calendar. The list of calendars and events in the
calendar are simple listboxes, to make it simpler
to understand.The application starts in much the
same way as the discovery service demo:
Figure 6: Configuring application credentials
procedure TMainForm.FormCreate(Sender: TObject);
begin
// Set up Google client.
FClient:=TGoogleClient.Create(Self);
FClient.WebClient:=TSynapseWebClient.Create(Self);
FClient.WebClient.RequestSigner:=FClient.AuthHandler;
FClient.AuthHandler.WebClient:=FClient.WebClient;
FClient.AuthHandler.Config.AccessType:=atOffLine;
// We want to enter a code.
FClient.OnUserConsent:=@DoUserConsent;
// Create a calendar API and connect it to the client.
FCalendarAPI:=TCalendarAPI.Create(Self);
FCalendarAPI.GoogleClient:=FClient;
// Register calendar resources.
TCalendarAPI.RegisterAPIResources;
LoadAuthConfig;
 LAZARUS NOW CAN USE GOOGLE APIS PAGE 10

The code differs only in the setup of the
authentication handler: The webclient's
RequestSigner property is set to the
Google Client AuthHandler property.
When the webclient needs to sign a
request (basically, it adds an
authorization handler), it checks the
AuthHandler. This will check if an
access token is available. For the
authentication handler to be able to do
its work, 2 properties must be set:
Procedure TMainForm.DoUserConsent(Const AURL: String;
Out AAuthCode: String);
begin
// Make the code entry visible.
GBAccess.Visible:=True;
EAccessCode.Text:='<enter code here>';
FAccessState:=acsWaiting;
// Show the URL in the browser
OpenUrl(AURL);
// Wait for the user to enter the code
While (FAccessState=acsWaiting) do
Application.ProcessMessages;
// If the user has entered the code, return it
if FAccessState=acsOK then AAuthCode:=EAccessCode.Text;
GBAccess.Visible:=False;
end;

FClient.AuthHandler.Config.AccessType:=atOffLine;
FClient.OnUserConsent:=@DoUserConsent; The code for this event handler looks like the
example above:

The first line tells the authentication handler class The code starts by showing the button and edit
that the application is an offline application. control. It then repeatedly runs the application
The second line registers an event handler: for an message loop to wait for the user to enter the
offline application, this event handler is called if authorization code. The OK and Cancel buttons
user consent is needed. The last line of the simply set a state, which is picked up in the loop:
OnCreate event handler loads the configuration procedure TMainForm.BSetAccessClick(Sender: TObject);
from an ini file; we'll get back to this. begin
FAccessState:=acsOK;
Now, when the application needs to do a service end;
call to a Google service, the authentication
procedure TMainForm.BCancelClick(Sender: TObject);
handler will check if it has an access token. If it begin
does not, and it does not have a refresh token FAccessState:=acsCancel;
(with which it can ask an access token from end;
Google), it will call the DoUserConsent event
handler.
Obviously, it would be annoying for the user to
When the event handler is called, several things
have to login and enter this code each time the
must be done:
application is used.
1. The event handler gets an URL to a Fortunately, this is not necessary: the application
Google authentication server, saves the tokens it received after the first calls to
which must be displayed in a browser. the server.
2. The Google authentication server procedure TMainForm.SaveRefreshToken;
will then ask the user to log in Var ini:TIniFile;
(if he or she is not yet logged in) and begin // We save the refresh token for later use.
will ask permission for your With FClient.AuthHandler.Session do
if RefreshToken<>'' then
application to access the calendar.
begin ini:=TIniFile.Create('Google.ini');
3. The browser will then display an try
authorization code, which must be With ini do
begin
entered by the user in the program.
WriteString('Session','RefreshToken',RefreshToken);
4. Once the user has entered the WriteString('Session','AccessToken',AccessToken);
authorization code, the event WriteString('Session','TokenType',AuthTokenType);
handler may return, passing the WriteDateTime('Session','AuthExpires',AuthExpires);
code back to the authorization WriteInteger('Session','AuthPeriod',AuthExpiryPeriod);
end;
handling component. finally
In the calendar demo application, Ini.Free;
there is a groupbox with an edit end;
control and 2 buttons (OK and Cancel). end;
end;
In this edit control the user can enter
the authorization code returned by
Google. Initially, this groupbox is invisible.

34 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

 LAZARUS NOW CAN USE GOOGLE APIS PAGE 11

The code below shows what properties of the user

session must be saved. For safety reasons, it is
better not to save the AccessToken in a desktop
application.

But for instance in a CGI web application, the

access token can better be saved, to avoid having
to exchange the refresh token for an access token
each time the Google service needs to be called.
In the OnCreate handler of the application, an
attempt is made to load these tokens from the ini
file, together with the client ID and secret:

procedure TMainForm.LoadAuthConfig;
Var ini:TIniFile;
begin
ini:=TIniFile.Create('Google.ini');
try
With FClient.AuthHandler.Config,Ini do begin
// Registered application needs calendar scope
ClientID :=ReadString('Credentials','ClientID','');
ClientSecret :=ReadString('Credentials','ClientSecret','');
AuthScope :=ReadString('Credentials','Scope', 'https://www.googleapis.com/auth/calendar');
// We are offline.
RedirectUri:='urn:ietf:wg:oauth:2.0:oob';
end;
With FClient.AuthHandler.Session,Ini do begin
// Session data
RefreshToken:=ReadString('Session','RefreshToken','');
AccessToken:=ReadString('Session','AccesToken','');
AuthTokenType:=ReadString('Session','TokenType','');
AuthExpires:=ReadDateTime('Session','AuthExpires',0);
AuthExpiryPeriod:=ReadInteger('Session','AuthPeriod',0);
end;
finally
Ini.Free;
end;
end;

If the application is run the first time, the session

tokens are empty, and the user consent event will
be called. Later runs of the application will load
the refresh and access token from the ini file, and
the user no longer needs to log in or enter an
access code. Unless he revokes the right of the
application to work on his/her behalf.
Needless to say, these tokens should be stored in a
safe way. The above method of loading the client
secret and ID was implemented done for
convenience, but is not recommended for use in
real life applications: the Client ID and Client

Secret must be secret, and an .ini file is not

suitable for this.
The code to fetch the events and calendar list is in
fact very similar to the code used in the discovery
demo, but we'll show it anyway:

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 35

 LAZARUS NOW CAN USE GOOGLE APIS (FOR ANDROID) PAGE 12 - END

procedure TMainForm.BFetchCalendarsClick(Sender: TObject);

var Entry: TCalendarListEntry;
Resource : TCalendarListResource; EN: String; i:integer; About the Author
begin Michael Van Canneyt has been a
LBCalendars.Items.Clear; contributor to Free Pascal since
FreeAndNil(CalendarList);
almost 20 years. He works mostly
Resource:= Nil;
try on the documentation, Linux
Resource:=FCalendarAPI.CreateCalendarListResource; platform support and Database and
CalendarList:=Resource.list(''); Web programming classes.
SaveRefreshToken; Naturally, he uses all this code also
if assigned(calendarList) then
for i:= 0 to Length(calendarList.items)-1 do
professionally.
begin
Entry:=calendarList.items[i];
EN:=Entry.Summary;
if EN='' then
EN:=Entry.id+' ('+Entry.description+')';
LBCalendars.Items.AddObject(IntToStr(i)+': '+EN,Entry);
end;
BFetchEvents.Enabled:=LBCalendars.Items.Count>0;
finally
FreeAndNil(Resource);
end;
end;

Figure 7: The calendar demo program in action

The code differs on 2 accounts: Conclusion

The code does not make use of the default
calendarlist resource of the Calendar API.
Instead it uses the
CreateCalendarListResource to create
a private instance, which is freed at the end
of the routine.
After the call to list the calendars is made,
the SaveRefreshToken routine is called
explicitly to save the refresh token. This can
also be handled in different ways: The
TOAuth2Handler has an event called
OnAuthSessionChange which is called
whenever the session information changes,
and the Store property which can be set
to a component that handles storing and
retrieving of session and configuration
variables.
REST is an important architecture in web APIs.
When done right, it makes developing a client
library very easy. Google offers a complete REST
API for its services, and Lazarus and Free Pascal
now contain now a complete client-library
implementation for the Google APIs, as has been
demonstrated here. This client library is somewhat
young and certainly subject to improvement, but is
certainly usable. Not all aspects have been treated
here: much more can be said about authentication,
getting information about the logged in user, and
saving sesion state information. A similar library
for the Microsoft Office365 environment is
currently being developed. All these topics will be
treated in a future article.
The author is indebted to Ludo Brands and the late
Reinier Olislagers for their ideas on how to handle
serialization and implementation of the OAuth 2
protocol.

The result of all this code can be seen in figure 7 in

the middle of this page.

36 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

ARDUINO: THE VISUINO PROJECT - PART 1
BY BOIAN MITOV
starter expert
Delphi
The Arduino board: a guide to quickly
get you started using Delphi
or: How a new product comes into
being.
How to quickly and efficiently start
using Arduino, and connect to it from
Delphi, and how a new product is born.
Today as Delphi and FPC developers, we feel
masters of our Desktops, Servers, and Mobile
devices, but we lack that mastery once we are
outside this digital world. Whenever we need to
control some other equipment, or collect some
interesting data from sensors, we feel that lack of
power, that we have grown to enjoy.
This was the feeling that drove me at the end of the
last year, to buy myself an Arduino board with a
small starter sensors and peripherals kit.
Arduino is an open source hardware platform,
developed initially primarily by Massimo Banzi,
David Cuartielles, Tom Igoe, Gianluca Martino and
David Mellis. The Arduino team/teams also
manufacture and sell Arduino boards, however since
the platform is Open Source, there is a huge
number of other manufacturers of Arduino
compatible boards ranging in prices from ~$1 to
~$100, and with huge range of sizes, some smaller
than a quarter, and a huge range of capabilities,
from few digital and analog pins, all the way to
WI/FI, and GSP enabled boards, with high number
of digital, and analog pins.
This great diversity, in capabilities, sizes, and
prices, makes Arduino a very attractive development
platform, for almost any project that requires
monitoring, interfacing or controlling the world
outside our comfortable Delphi/FPC controlled
boxes, or at least that is what I thought...
I received my Arduino KIT, anxiously unpacked it,
and hooked it to my system.
So far so good, it started to blink.
Then I started digging the web to learn how to
program it, and my fantasy to control the world
with it came crashing down on me. The Arduino
boards are usually programmed using a very
simple to use but extremely rudimentary IDE called
Arduino IDE, in C/C++, with very low level code,
that requires fairly deep hardware, and firmware
knowledge to do even relatively simple tasks.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
PAGE 1
It took me hours to put even fairly simple code
together - reading from one sensor, and controlling
a motor. Hardly impressive achievement.
To become the master of the world with my
Arduino, I would need a better approach.
Since obviously, nobody else had solved the
problem I was facing, I decided to do it myself,
and got down to work. Here is what my goal was:
1. In order a development tool to be attractive to
inexperienced developers it must be very easy
to use. It had to be easy enough for a kid to
learn it, and it should not require you to learn
programming language or programming
techniques. In short, it should be intuitive
visual design tool.
2. In order for it to be attractive to experienced
and expert developers, it must produce
compact, and highly efficient, scalable code.
3. Since Arduino didn't have an operating
system, it must allow components to be
designed as a collaborative plug-in framework,
so they can work together, and not interfere
with each other. In essence a small
rudimentary, component oriented OS core
was needed.
Fortunately for me, I was already experienced in
developing high performance component
frameworks for Delphi, C++ Builder, and .NET, as
well as haaving a solid hardware background.
I also had a ready graphical development IDE for
Windows called OpenWire Studio. OpenWire Studio is
a very flexible and open architecture Graphical
IDE, and can easily be adapted to program almost
anything.
At least in theory, now here was the chance for it
to prove that it is up to the task solving my little
Arduino problem.
I started with the most difficult of the problems.
Writing a component framework and very
rudimentary scheduling functionality. For this I
used a very rudimentary lightweight flavor of the
good old OpenWire, implemented in C++.
Next I created few Delphi components and using
the new Mitov.Runtime RTTI started to generate
corresponding C++ code for Arduino from them.
Finally I cloned the OpenWire Studio, and
installed the newly created components in it.
And the first version of Visuino was born. All that
was needed was to add buttons to generate the
Arduino code, and to start the Arduino IDE so I could
compile the code.
37
ARDUINO: THE VISUINO PROJECT - PART 1
This happened exactly in the middle of the Delphi
Week, celebrating 20 years of Delphi, and so as I
did a brief live interview about my experience with
Delphi over the years, David I and Jim McKeeth,
suggested to show the Visuino as example of what
can be achieved with Delphi.
So it was, that the first people to see the product
live in action (bugs and all), were the Delphi fans
watching the Delphi Live broadcast!
At this point I already had achieved all the goals
I had in mind, when I started the project.
All I needed was to write more components,
and play with it, but soon I started to discover
more shortcomings. I was able to program my
Arduino with great ease, but my Arduino and my PC
were living in separated worlds.
I wanted to see on my screen, what my Arduino
was collecting as data, or processing. As a
minimum, I needed a terminal window, so I
created an OpenWire serial port component, and
hooked a terminal window, with the necessary user
interface. I was able to see my data, but it was in
text format. What if I need to see it in a plot?
Figure 1
38
PAGE 2
So using PlotLab, I naturally added a Scope
component and hooked it to the serial port.
The Visuino was shaping very well. Not only could
I program my boards with it, but I could also
monitor and plot the data from one channel.
But what if I need to monitor more channels?
I still was not satisfied. To send data from
multiple channels, over a single communication
channel, I needed to package the data in some
form of structure, so I designed a package and un-
package components that allow the data to be
packaged and transmitted as a structured packet.
Now I was able to plot multiple channels easily.
I went even further, allowing Visuino to
automatically configure the scope from the
package format in my Arduino design.
Scope piloting was nice, but sometimes we want to
see the data in Gauges, and LEDs so I decided to
add instrumentation view as well, using the
InstrumentLab component package. My Visuino was
feature complete, I was happy, and I already had
Delphi components developed that allowed me to
easily communicate with the board.
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE
ARDUINO: THE VISUINO PROJECT - PART 1 PAGE 3

The next logical step was to package and release

them, so other developers can communicate with
Arduino from their Delphi applications.

Now that we are trough with the short Visuino

history, it is time to take a real look at it.
You can download the Visuino Beta by visiting
www.visuino.com .

Before installing make sure you have the latest

version of the Arduino IDE installed.
Currently this is 1.6.4 and is available for
download here :
http://www.arduino.cc/en/Main/Software
.
The Arduino IDE comes with all standard Arduino Figure 2
libraries that will be needed to compile the code
generated by Visuino.
After installing the Arduino IDE, you can go ahead
with the Visuino installation.
If you have done a default installation of your Figure 3
Arduino IDE, there will be no need to do any
Once you have familiarized
configuration of Visuino.
yourself with the demos, you
Once installed you can start Visuino.
can try to create a new project yourself. The design
area always contains an Arduino component.
In the center you will have the Visuino's design
You can select the Arduino board type by setting the
area. This is where you will visually design your
BoardType property or by clicking on the setup
project.
icon of the Arduino component.
On the right of figure 1 (page before) is the Figure 4
component toolbar where the components are The simplest project is a
organized in different categories and sub- blinking LED. Drop a
categories. Pulse Generator from
the toolbar.
In the top left corner of figure 1 (page before) is the
overview navigation area, and bellow it is the Connect it to
property editor. pin 13 of the Arduino
Below the Design Area is located the Serial component.(figure 5)

Terminal the Scope and - as we will see later - the

Instruments Panel.

The best place to start learning is to watch the

Visuino video tutorials:
https://www.youtube.com/watch?v=v- Figure 5
yMtIzgIeU,
Now your design is ready, and you can generate
and the Arduino code by clicking on the Send to
Arduino IDE for Compilation button:
https://www.youtube.com/watch?v=wKKlhg
KtDoI

The next step is opening the included demo

projects. You can easily access them from the menu
by selecting |File|Open Demo...|

Figure 6

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 39

ARDUINO: THE VISUINO PROJECT - PART 1 PAGE 4

This will generate the Arduino code, and launch

the Arduino IDE where you can compile and
upload the compiled code into your Arduino board:

Figure 8

In the Bytes editor type 55 55 . This will be used

to identify the starting point of a package.
You can use any number of bytes, with any values,
but 2 bytes are a good choice, and common values
such as 00 00 should be avoided as they often
appear in data. The component makes sure the
header is properly recognized even if 55 55 is
present in the data, by special encoding.
Figure 7

Next we can connect a few sensors to the Arduino

pins, and monitor them in Visuino.
Start a new Visuino project, by selecting |File|New|.
Add a Packet component to the Design:

Figure 9

You can close the editor by clicking on the OK

button.

Double-click on the Packet1 to open the elements

editor:

And connect its output to the Input of the Serial Port

(The software input for the serial receives data that
will be sent as serial output from the hardware. )

In the property editor expand the HeadMarker

and click on the ...ellipsis button: Figure 10

40 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

ARDUINO: THE VISUINO PROJECT - PART 1 PAGE 5

With this editor you can add data channels to the

packet. For this example I will add 2 Analog and 2
digital channels.
Now we can connect the packet elements to the
pins where our sensors are connected:

Figure 11
Your design is ready. You can generate, compile,
and upload the code to your Arduino. Now you
can use the Visuino Scope and Instrumentation
Panel to view the data. Select the com port to which
the Arduino is connected, and from the Format
drop-down select Packet1: Then click Connect.

Figure 12

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 41

ARDUINO: THE VISUINO PROJECT - PART 1 PAGE 6

Figure 13

In the scope you can see the data arriving from the
sensors: see figure above
And the same data can be seen
in the Instrument Panel:

Figure 14

You have seen how you can receive

and visualize data from sensors in the
Visuino. In the next issue you will
learn how to receive data from
Arduino into your Delphi applications.

42 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

GENERATE DELPHI SUPPORT FOR READING
AND WRITING XML FILES PAGE 1
- THAT ADHERE TO THE GOOGLE MERCHANTS RATING DATA SPECIFICATIONS
starter expert
Delphi
This article is actually less about how Google
Merchants ratings work, and more about the
principle of utilizing kbmMW to convert XSD (XML
schema documents) to easily streamable Delphi
objects.
kbmMW Enterprise Edition includes a complete
XSD schema converter, which takes an xsd file as
input and outputs readily compilable Pascal
objects, that are very easy to read, alter and
stream to and from XML and JSON.
BY KIM MADSEN
First download the XSD from Google here:
https://developers.google.com/
merchant-review-feeds/schema
Next one have to compile (if not already done) and
run the kbmMW ConvertXSD.exe application.
Now click Convert XSD file, and select the
downloaded merchant_reviews.xsd file.
A split second later, the file has been read, validated
and a merchant_reviews.pas file has been generated
in the same directory.

First a little bit about the XSD

schema converter.
Its delivered as a demo application
(that is full featured in what it does),
but which can be tailored if
required to any developers need.
Its main internal components, are
a TkbmMWXSDParser class (with
a number of assistant classes),
a TkbmMWXSDPascalCodeGen
class (descending from
TkbmMWXSDCustomCodeGen)
and of course the TkbmMWDOMXML
class for speedy and complete
handling of the XML, in which
XSD files are written.
As can be seen, its actually
possible to utilize the parse tree
generated by the XSD parser to
output other types documents by
inheriting from the
TkbmMWXSDCustomCodeGen.
That's however out of scope for
this article.
Ive done some comparisons with
the built in XSD importer tool in
Delphi, and find that the kbmMW
ConvertXSD tool is better and more
accurate in converting XSD
documents, and easily converts
XSD documents not possible
using Embarcaderos XSD inporter.
The outset for this article is to
generate Delphi support for
reading and writing XML files
that adhere to the Google In the right pane, its possible to see which classes
merchants rating data kbmMW's XSD converter have found. And in the left
specifications. pane, any warnings or errors would have been listed.

FINALLY ITS EASY

TO CREATE AND READ
XML FILES
Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 43
 GENERATE DELPHI SUPPORT FOR READING
AND WRITING XML FILES PAGE 2
unit merchant_reviews;
The converted file looks like this (snippets only shown):
// ==========================================================================
// Generated by kbmMW XSD Converter
// 5/11/2015 01:08:59
// Based on: C:\svn_c4d\kbmmw\trunk\ConvertXSD\GoogleMerchantFeedback\merchant_reviews.xsd
// ==========================================================================

// Log:
// Converted without errors or warnings.

type

(*$HPPEMIT 'namespace Merchant_reviews {'*)

{$SCOPEDENUMS ON}
TLanguageCode =
(aa,ab,ae,af,ak,am,an,ar,&as,av,ay,az,ba,be,bg,bh,bi,bm,bn,bo,br,bs,ca,ce,ch,co,cr,cs,cu,cv,cy,da,de,dv,dz,ee,el,en
,eo,es,et,eu,fa,ff,fi,fj,fo,fr,fy,ga,gd,gl,gn,gu,gv,ha,he,hi,ho,hr,ht,hu,hy,hz,ia,id,ie,ig,ii,ik,io,&is,it,iu,ja,jv
,ka,kg,ki,kj,kk,kl,km,kn,ko,kr,ks,ku,kv,kw,ky,la,lb,lg,li,ln,lo,lt,lu,lv,mg,mh,mi,mk,ml,mn,mr,ms,mt,my,na,nb,nd,ne,
ng,nl,nn,no,nr,nv,ny,oc,oj,om,&or,os,pa,pi,pl,ps,pt,qu,rm,rn,ro,ru,rw,sa,sc,sd,se,sg,si,sk,sl,sm,sn,so,sq,sr,ss,st,
su,sv,sw,ta,te,tg,th,ti,tk,tl,tn,&to,tr,ts,tt,tw,ty,ug,uk,ur,uz,ve,vi,vo,wa,wo,xh,yi,yo,za,zh,zu);
TCountryCode =

Ttype_1 = (singleton,group);
TNonEmptyString = kbmMWNullable<string>;
Ttype = (summary,detail);
Treviewer_type = (user,editorial,aggregator);
Tcollection_method = (unsolicited,point_of_sale,after_fulfillment);

const
CLanguageCode : array[TLanguageCode] of string =
('aa','ab','ae','af','ak','am','an','ar','as','av','ay','az','ba','be','bg','bh','bi','bm','bn','bo','br','bs','ca'
,'ce','ch','co','cr','cs','cu','cv','cy','da','de','dv','dz','ee','el','en','eo','es','et','eu','fa','ff','fi','fj'
,'fo','fr','fy','ga','gd','gl','gn','gu','gv','ha','he','hi','ho','hr','ht','hu','hy','hz','ia','id','ie','ig','ii'
,'ik','io','is','it','iu','ja','jv','ka','kg','ki','kj','kk','kl','km','kn','ko','kr','ks','ku','kv','kw','ky','la'
,'lb','lg','li','ln','lo','lt','lu','lv','mg','mh','mi','mk','ml','mn','mr','ms','mt','my','na','nb','nd','ne','ng'
,'nl','nn','no','nr','nv','ny','oc','oj','om','or','os','pa','pi','pl','ps','pt','qu','rm','rn','ro','ru','rw','sa'
,'sc','sd','se','sg','si','sk','sl','sm','sn','so','sq','sr','ss','st','su','sv','sw','ta','te','tg','th','ti','tk'
,'tl','tn','to','tr','ts','tt','tw','ty','ug','uk','ur','uz','ve','vi','vo','wa','wo','xh','yi','yo','za','zh','zu'
);
CCountryCode : array[TCountryCode] of string =

Ctype_1 : array[Ttype_1] of string = ('singleton','group');

Ctype : array[Ttype] of string = ('summary','detail');
Creviewer_type : array[Treviewer_type] of string = ('user','editorial','aggregator');
Ccollection_method : array[Tcollection_method] of string = ('unsolicited','point_of_sale','after_fulfillment');

[kbmMW_Root('Review',[mwrfIncludeOnlyTagged])]

When one is creating a project that needs

to read or write XML files that adhere to
the Google merchants ratings XSD, one
simply need to include this file in the uses
clause, and then use kbmMW's
serialization and deserialization methods
to convert XML or JSON to objects or
objects to XML or JSON.
At
https://developers.google.com/
merchant-review-feeds/sample
there is a sample XML file provided by
Google, which we will use to see that we
can convert the XML to objects.

A new VCL application is created (it could

be a Firemonkey application too, kbmMW
works in both environments).

44 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

 GENERATE DELPHI SUPPORT FOR READING
AND WRITING XML FILES PAGE 3

In its uses clause we add the generated

merchant_review unit:
uses
Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes,
Vcl.Graphics, Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls,
merchant_reviews;

Before serializing or deserializing we need to let kbmMW have full support for timezones, and you
kbmMW know about the classes that are part of the can operate the TkbmMWDateTime in much the
merchant_reviews unit. This is done in the same way as you would with a TDateTime.
OnFormCreate event in this sample: Ok.. then let us try to serialize the FFeed object
procedure TForm1.FormCreate(Sender: TObject); back to XML again potentially after we have made
begin changes to it, or perhaps even built a new Tfeed
Tmerchant_reviews.RegisterStreamableObjects;
instance from scratch.
end;
procedure TForm1.btnSaveClick(Sender: TObject);
Now everything is ready for streaming. Lets put var xmlm:TkbmMWXMLMarshal; xml:TkbmMWDOMXML;
some code in the load XML buttons event handler to begin
if FFeed=nil then exit;
load a Google merchants ratings XML file and have it
accessible via standard Delphi objects: xmlm:=TkbmMWXMLMarshal.Create;
try
procedure TForm1.btnLoadClick(Sender: TObject); xmlm.Typed:=false;
var xml:=xmlm.ValueToDOMXML(FFeed);
xmlm:TkbmMWXMLMarshal; xml:TkbmMWDOMXML; if xml=nil then
m:TMerchant; r:TReview; d:TNonEmptyString; begin
begin Memo1.Lines.Add('xml=null');
xml:=TkbmMWDOMXML.Create; exit;
try end;
xml.LoadFromFile('merchant_reviews.xml'); finally
xmlm:=TkbmMWXMLMarshal.Create; xmlm.Free;
try FFeed:=TFeed(xmlm.ValueFromDOMXML(TFeed,xml)); end;
Use the FFeed object for what you want. xml.Typed:=false;
finally xmlm.Free; xml.AutoIndent:=true;
end; xml.AutoLineFeed:=true;
finally xml.Update;
xml.Free; xml.SaveToFile('newfeed.xml');
end; xml.Free;
end;

Its that simple to convert the XML to true Delphi

objects! Now you can access all fields/attributes
like this:
Memo1.Lines.Add('FFeed.merchant.review.reviewer_id='+r.reviewer_id.ValueOr['<null>']);
Memo1.Lines.Add('FFeed.merchant.review.reviewer_type='+Creviewer_type[r.reviewer_type]);
Memo1.Lines.Add('FFeed.merchant.review.review_date='+r.review_date.ISO8601String);
Memo1.Lines.Add('FFeed.merchant.review.is_spam='+BoolToStr(r.is_spam.ValueOr[false]));

Notice the optional use of .ValueOr[]. The reason

is that for example reviewer_id is a nullable
value. kbmMW understands the difference between for
example a null string value and an empty string.
Similarly kbmMW understands nullable
integers, singles, doubles, Booleans,
dates, times, date/times etc.
Also notice the access of the review_date
property. We want to display it as an ISO8601
formatted string in this case, but we could also have
asked it to be shown as a RFC1123 formattet string
instead or as a local date/time or as a GMT
date/time.
It's as simple as that! Now a newfeed.xml file will
have been generated based on the FFeed object.
It will be data wise exact the same as the original xml
file we deserialized, although it may differ in
order or in filtering out empty XML nodes.
What if you would want to send the Ffeed object
instance to a browser, connected to a kbmMW
application server that is acting as a web server?
The browser usually understands Javascript, and
often jQuery is used for sending requests to a
webserver and receiving responses in what is called
an AJAX operation (Async Javascript and XML).

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 45

 GENERATE DELPHI SUPPORT FOR READING
AND WRITING XML FILES PAGE 4

As such, the browser typically do support parsing
XML to an extent, potentially via 3rdparty XML
Javascript libraries. However Javascript supports a
native textual object notation, that is more compact
than XML and faster for it to read. JSON is the name
for that notation (Javascript Object Notation).
So a better choice is to serialize the Ffeed object to
JSON and send that JSON stream to the browser.
The browser would see the streamed data as true
Javascript objects upon reception.
In kbmMW its simple to serialize to JSON:
procedure TForm1.btnSaveJSONClick(Sender: TObject);
var jm:TkbmMWJSONMarshal; s:string;
begin
if FFeed=nil then exit;
jm:=TkbmMWJSONMarshal.Create;
try
s:=jm.ValueToString(FFeed);
Now the string s contains the JSON data
finally jm.Free;
end;
end;
The string can be sent directly to the browser as a
response to the browsers GET or POST request,
giving the mimetype application/json.
What makes the serialization/deserialization magic
happen is the combination of attributes given on the
Delphi types, and an advanced and intelligent built in
mechanism that understands the combination of
attributes and the type and relations between the
defined Delphi types that are to be
serialized/deserialized.
kbmMW's serializer is probably one of the most
advanced on the market, and is even
included in the free kbmMW CodeGear Edition.
A Delphi class can be decorated with a
number of attributes that hints to the
serializer/deserializer how it should go
about its operation.
This is a short explanation of the basic forms
of various attributes currently understood
by kbmMW:

[kbmMW_Ignore] Can be placed in front of any field or property to ensure that that particular field/property is not serialized. Eg.
[kbmMW_Ignore] property SomeValue:string read.
[kbmMW_NotNull] Can be placed in front of any field/property to indicate that the field must NOT take the value of NULL (undefined).
If it does, an exception will be raised upon serialization or deserialization.
[kbmMW_Element(..)] Place in front of any field/property to indicate that the value should be serialized as an element (a child node in XML).
Its also possible to specify the name of the child object like this: [kbmMW_Element('someName')]
[kbmMW_Attribute(..)] Similar to the kbmMW_Element, except that it directs that the value must be put in an attribute (in the parent node in
XML). For JSON it will work the same as kbmMW_Element. This attribute also accepts a naming argument.
[kbmMW_Root(..)] Specifies default naming of a class, and what parts of it should automatically be serialized/deserialized like all published
properties, all public properties or only properties/fields tagged with kbmMW_Attribute or kbmMW_Element attributes.
[kbmMW_Null(..)] Indicate that the element can take the value of NULL. Optionally a default value can be provided, which will be used in
case the value in the XML/JSON indicates NULL.
[kbmMW_Validate()] Validates a property/field or a complete class instance for its values and raises an exception if a value is out of spec.
A complete expression which can refer to any field in the class can be given. If the expression evaluates to false,
then an exception will be raised upon serialization/deserialization time.
Eg. [kbmMW_Validate('$someName=22')] accepts only the value 22 in the someName field.

Further there are special attributes:

[kbmMW_ConditionalType()] Controls (in combination with [kbmMW_Root]l) serialization and deserialization
of colletions containing different types of child objects within the same
collection.[kbmMW_Dataset(..)]
[kbmMW_Dataset(..)] Controls serialization/deserialization of fields/properties that are of type
[kbmMW_DatasetRow(..)] TkbmCustomMemTable or descendants.
[kbmMW_DatasetField(..)]
[kbmMW_DatasetVersion(..)]
[kbmMW_DatasetDefinition(..)]
[kbmMW_DatasetData(..)]

46 Issue Nr 3 2015 BLAISE PASCAL MAGAZINE

GENERATE DELPHI SUPPORT FOR READING
AND WRITING XML FILES PAGE 5 - END

Finally its possible to register custom
serialization/deserialization code for handling
special serialization/deserialization requirements.
It already comes with such for handling
kbmMWNullable<..> types, TkbmMWDateTime
types, TStream types/descendants and
TkbmCustomMemtable descendants.
I hope this has given an appetizer for how versatile
the kbmMW object serialization/deserialization
framework is.
As an example of a fairly complex XSD that kbmMW
effortless converts and serializes/deserializes
accordingly to, but that even Delphi XE8 fails
converting, is the Personal Health Record XSD
found here:
http://www.recordsforliving.com/
Schemas/2006-04/PHR-
Model/R4L_PHRModel.xsd
As kbmMW is a modular framework, one can choose
only to use its XML capabilities, its JSON capabilities,
its serialization capabilities, its application server
capabilities, its database capabilities, its stream
storage capabilities, its memory table or its async
messaging capabilities etc without having to use all
other parts of the kbmMW framework.
But obviously, you will get the best of the best if
you take the plunge and choose to take advantage
of all the kbmMW features you need in your
applications as all parts are designed to work in
perfect harmony with each other.
/Kim Madsen / C4D
There is extra code you can download from your
subscription site....

You can find sample data here:

http://www.recordsforliving.com/Persona
lHealthRecords/SamplePHRs.aspx

30,00 including VAT 39

including the printed book,
ebook and shipping

Quick answers to common problems

See our special offer:

if you take out a subscription
Delphi Cookbook for two years the book
50 hands-on recipes to master the power of Delphi for
will cost you only 10,00
cross-platform and mobile development on Windows,
HOICE A
Mac OS X, Android, and iOS SC
R BLAISE
M
TO

AZING

PASCAL
DI

MAGAZINE
Daniele Teti E

http://www.blaisepascal.eu/daniele_teti_book/DanieleTeti.html

Issue Nr 3 2015 BLAISE PASCAL MAGAZINE 47

EXTREME PERFORMANCE
NOW FASTER THAN EVER!

COMPOELOPERS
DEV
4 NENTS
- Now faster than ever!
- Improved publish/subscribe message queues
- Improved XML/JSON marshalling support
- Delphi/C++Builder/RAD Studio XE8
- Native high performance 100% developer Supports Delphi/C++Builder/RAD Studio 2009
defined application server with support for to XE8 (32 bit, 64 bit and OSX where applicable).
loadbalancing and failover kbmMW for XE5 to XE8 includes full support for
- Native high performance JSON and XML Android and IOS (client and server).!
(DOM and SAX) for easy integration with
kbmMemTable is the fastest and most feature rich
external systems in memory table for Embarcadero products.
- Native support for RTTI assisted object
marshalling to and from XML/JSON, now also - Easily supports large datasets
with new fullfeatured XML schema with millions of records
(XSD) import - Easy data streaming support
- High speed, unified database access - Optional to use native SQL engine
(35+ supported database APIs) with - Supports nested transactions and undo
- Native and fast build in M/D,
connection pooling, metadata and
aggregation /grouping,
data caching on all tiers range selection features
- Multi head access to the application server, - Advanced indexing features for
via AJAX, native binary, Publish/Subscribe, extreme performance
SOAP, XML, RTMP from web browsers,
embedded devices, linked application Warning!
servers, PCs, mobile devices, Java systems kbmMemTable and kbmMW
and many more clients
- Full FastCGI hosting support. Host PHP/Ruby
are highly addictive!
Once used, and you are hooked for life!
/Perl/Python applications in kbmMW!
- KBMMW V. 4.80 AMQP support
( Advanced Message Queuing Protocol)
- Added AMQP 0.91 client side gateway
support and sample.
- Updated StreamSec TLS transport plugin
component (by StreamSec).

COMPONENTS
4
- Improved performance on Indy TCP/IP
Client messaging transport for large number
of inbound messages.
DEVELOPERS
EESB, SOA,MoM, EAI TOOLS FOR INTELLIGENT SOLUTIONS. kbmMW IS THE PREMIERE N-TIER PRODUCT FOR DELPHI /
C++BUILDER BDS DEVELOPMENT FRAMEWORK FOR WIN 32 / 64, .NET AND LINUX WITH CLIENTS RESIDING ON WIN32 / 64,
.NET, LINUX, UNIX MAINFRAMES, MINIS, EMBEDDED DEVICES, SMART PHONES AND TABLETS.