If you've ever included a Flash movie on a page this will be a familiar issue to you. The question of how best to embed the Flash plugin has a long history - the various browsers have made plugin detection notoriously awkward, but over the years a standard practice of sorts, has developed to the point where you can find numerous helpful scripts, and Adobe now provide a Flash Player Detection kit along with guidelines for detection.

Unfortunately, Curl doesn't provide an equivalent script for doing this so you've been on your own - until now, that is. I've written some Javascript that will do the job for you, based on the best example I could find for Flash - SWFObject script developed by Geoff Stearns. In the spirit of the original, I've called it CurlrObject, and it is a Javascript-only detection, avoiding the use of VBasic on PCs. As an added bonus, I've included in the script a way of specifying parameters for the applet - to answer another frequently asked question.

If you're in a hurry you can view the code and you can download it from the Code page. Read on for usage notes.

CurlrObject is surprisingly easy to use. Just include the script file in your web page, add a couple of lines of Javascript and identify a HTML element to contain the Curl applet. For example:

The parameters for CurlrObject are:

parameter	Description
appletUrl	The location of the Curl applet to be run.
width	The width of the Curl applet
height	The height of the Curl applet
version	The required version of the Curl RTE
id	(optional) The id to be used for the embed tag.
redirectUrl	(optional) The location for the RTE install. Defaults to http://www.curl.com/download/index.php.

Like the SWFObject the net result of successful detection is to place and populate an <embed> node into the target element. In other respects CurlrObject has behavior that is a little different from SWFObject; in particular if the script cannot find the Curl RTE it writes a message to the target HTML element that includes a link to the Curl download page - or to the redirectUrl. Other diiferences are: the id parameter is optional, and no detectkey is specifiable.

One reason you may want to use a different redirectUrl from the default arises when require an older version of the RTE than is current - these are found at a different location on the Curl web site.

If you're familiar with Javascript, then you will probably feel comfortable customizing the functions getINSTALLCURLHTML and getDISABLEDCURLHTML to change the message or the behavior of the script when the RTE is not found.

Specifying parameters for the Curl applet.

You can use the CurlrObject to specify startup parameters for the applet; e.g.

This builds a query args list and attaches it to the applet Url. To extract the name value pairs in your Curl applet you'll need code like this procedure, which constructs an Arguments object from the applet's query arguments.

To see it in action you can run the sample page with three Curl applets requiring different RTE versions. (You don't have to install all the versions if you don't want to).

I've done some basic testing - but I'm not at all sure if the case of the RTE installed but not enabled works on all browsers - it doesn't in IE. If you use it and find problems or have improvements to suggest, let me know.

The curlr package COM.CURLR.PACKAGE provides a basic techology stack that can get you started building Awax applications with Curl. Previously I introduced the XML parser and the XML node classes and showed their use in reading and transforming an XML stream into a searchable hierarchy. In this article I'll examine the classes implementing the XML DOM and a Curl implementation of the XMLHttpRequest functionality and give tutorial on their use.

The reason for my providing this object is to enable some of the familiar and increasingly widespread Ajax programming patterns to be implemented using Curl with vey similar code. So similar, in fact that we can adapt the standard Ajax tutorial that's used to introduce the XMLHttpRequest object with very little change.

sadXMLHttpRequest tutorial

The basic tutorial shows the use of the asynchronous part of Awax, and provides a programming template for using the sadXMLHttpRequest object. Obviously there are many variations that you could implement using Curl -

Step 1: Construct the XMLHttpRequestObject

First you are taught to construct the object. This is trivial in Curl code, and of course is browser-independent:
|| Step 1. Create a sadXMLHttpRequest object let xmlhttp:sadXMLHttpRequest = {new sadXMLHttpRequest}

Step 2: Create Event handler

Next you are told to create an event handler for your page to be called as a result of a user action and which will invoke methods on the XMLHttpREquest object. Curl applets do not usually consist of a single page - though this and other tutorials do - and event handlers can be placed on any Curl GUI object displayed in the graphics hierarchy. for the purpose of this tutorial, we will create a button that will initiate a request for the headers of a page:
|| Step 2. Create an event handler that will issue a request let request-button:CommandButton = {CommandButton label="get headers", {on Action do {xmlhttp.open HttpRequestMethod.head, {url "http://www.curlr.org/"}, async? = true} } }

Step 3: Define state change actions.

The third step is to declare the set of actions to be performed when the state of the XMLHttpRequest object changes. This is the "Asynchronous Javascript" part of Ajax- since we are using Curl, its the asynchronous web application.
|| Step 3. Create a procedure to be called when the state of the sadXMLHttpRequest object changes. || first make a Frame to put the returned headers let display-frame:Frame = {Frame} set xmlhttp.onreadystatechange = || We could also use a static procedure {proc {}:void || use a switch statement on the state {switch xmlhttp.readyState case readyStateEnum.Open do || we could make the send call immediately after the open call, || doing it here shows the handling of the state change {xmlhttp.send} case readyStateEnum.Loaded do {if-non-null hdrs = {xmlhttp.getAllResponseHeaders} then || headers are returned as a string || show them in the frame {display-frame.add replace? = true, {pre {value hdrs}} } } } }

Complete the example with a display consiting of the button and the display frame.

Note that the tutorial uses a common pattern for changing part of the display of an application - the Frame container is placed where the dynamic content is to appear, and the method add is used with the parameter replace?=true.

tutorial app - this runs the tutorial application in a new window - click the button to display the headers -

The curlr implementation of the XMLHttpRequest object mostly follows the W3C spec - the source file details the differences, but they are summarized as follows:

• readyState is defined from the enumeration readyStateEnum.
• onreadystatechange is called when the readyState setter is called - not when a DOM event is raised.
• the check for xml content is made by searching the mime-type for the string "xml"
• uses a look-up table to find the statusText
• raises excpetion sadBadStateException for unexpected readyState
• does not support Http PUT and DELETE, does not support userinfo.

Using XML and sadXMLDom

The pattern we've just seen enables application behavior to be determined by the change in state of the XMLHttpRequest object. The interesting usage starts when the data returned by the request is in the form of XML.

The simple sadXMLDom provides a XML Document Object Model, with a root sadXMLNode through which the elements can be accessed. The sadXMLDom object also has a sadXMLParser object, which operates on thr Url or StringBuf defined as input to one of the factories of sadXMLDom; this can make the code less verbose than using the parser directly. For example, the feed code of the previous article could be written using the sadXMLDom as

When the sadXMLHttpRequest object is used to query an XML source the responseXML accessor prodives the parsed document as a sadXMLDom which can be used by the onreadystatechange handler, e.g.

A Simple Flickr RSS Viewer

With the information we now have about sadXMLHttpRequest and sadXMLDom we can put together an example of a RSS viewer.

We'll build the viewer as a simple Curl Dialog (see code page) to which we can add a Commit action, and which has these three imterfaces

current-feed-url - the Url of the selected feed

display-feed - a method that takes an sadXMLDom to pouplate the display

display-text - method which will display an input string

Using this object we can write code very similar in structure to the tutorial, to create the viewer:

Flickr RSS Viewer - this runs the result in a new window - simply select a feed in the dropdown list, then click on a thumbnail to see a larger version of the picture:

Reference

The methods and properties of sadXMLHttpRequest are summarized in this table

The Curl language provides a SAX parser, and the not yet published Curl web services developer's kit builds on it to provide a stack of standards compliant XML and web services utilities - which I strongly recommend for enterprise application development.

For many applications, however, we don't need the rigor of a validating XML parser, or the type definitions of a DTD. Particularly when XML is being used only as an exchange format, we simply need a mechansim for transforming the XML data stream into structures that can be queried for the required information. The more efficient and less verbose this is, the better for the developer, for whom the XML data is simply a means to the desired end of building a useful and interesting application.

This, then, is the purpose of the code that I've implemented in the package COM.CURLR.XML - namely to provide a simple and lightweight set of classes that are easy to use in application code. The beta version of the package is now checked in to the curlr repository.

I had been wanting to implement a simple XML parser for some time - but as there's not yet a Curl implementation of lex / yacc or a general purpose scanner / parser (a project for another day), this was always going to be a handcrafted piece of code, and one I hadn't had time to write.

After some searching I found this Java Quick and Dirty XML parser, intended at the time it was written for mobile implementations but clearly suitable now for handling XML in many client applications. This is a very lightweight implementation of the basic XML standard, but the original code would be inefficient if implemented "as is" in Curl. Also, the parser is written as an event handler, with call-backs for start / end document, and start / end element events, these are also not necessary in the curlr implementation, which incrementally creates a tree structure of nodes, with a single root element.

So, the particulars differ from the original, but the principles still apply. The parser is non-validating, and does not handle the xml header - so the encoding must be known to the caller, and should be set correctly when the input stream is opened. The DOCUMENT tag is treated as a comment, but there are DOCUMENT definitions that the parser will not handle. This emphasizes the main usage constraint of the parser - that the content of the XML is expected by the parser.

There are four important classes included in the package:

• sadXMLParser - parses a stream of XML format data into a tree of nodes
• sadXMLNode - a node representing a tag in an XML document, it has search functions
• sadXMLDom - a DOM representing the XML document, supporting the basic W3C search methods
• sadXMLHttpRequest - a Curl implementation of the XMLHttpRequest object used extensively in AJAX applications.

In this article I'll introduce the first two classes, essential for all XML handling, and which I have used to generate and implement the Flickr api - so we can be reasonably sure that it works well enough. The other two are intended to parallel the usage of the AJAX XmlHttpRequest object; I'll present these in my next article, and show how you can implement AJAX applications with very similar Curl code.

The parser, sadXMLParser, has only one public class to be used called, unsurprisingly, parse. This takes a TextInputStream as an input argument, and returns the root node of a hierarchy on successful completion; an exception is thrown if the XML is badly formed.

The returned tree node structure is implemented by sadXMLNode, and is as simple as possible; a node has a parent (unless it's the root node), and nullable fields are assigned to the table of attributes (they are actually stored as an Arguments object), and the array of child nodes. All attributes are defined as name / value pairs with the value stored as a String.

The node class has several methods useful for searching the tree structure and for managing the tree structure. For familiarity of programming - but not compliance - I've included getters equivalent to those in the W3C level 1 spec. Here's the skeleton of the code:

The combination of the parser and the search methods of the tree nodes give us all we need to handle most application scenarios - the root node is, in effect, our XML Dom. If you're happier working with a Dom object using the standard search functions like getElementById, then you'll prefer to use sadXMLDom.

Let's look first at using the classes to examine the XML from a Flickr group's RSS feed - we'll be creating a simple RSS viewer in the next article, so this has some relevance. The following code parses the XML from an RSS feed from the Flickr Central group.

The code is quite simple - first we create a readable stream for the feed. The example chooses to do this by resolving the url into a HttpFile object. If this was unsuccessful, a MissingFileException would be thrown - so obviously the example is missing some defensive try/catch blocks. Once the file handle is obtained, we create the input stream with a call to the synchronous method http-read-open. This approach gives us access to the http response headers, and allows us to set the http request headers in the http-read-open call. If this isn't necessary, then the following even simpler code, using the read-open procedure will be sufficient to give a readable TextInputStream. In either case, the read open is where we would set the character encoding for the stream.

The parser is reentrant, so we would need only the one object for all subsequent XML processing. The parse method takes any TextInputStream as a parameter, and returns the root sadXMLNode of the parsed tree. The final statement using the to-String method will simply display the XML tree as text - minus the XML header, with an extra root node; this will be quite ugly, since the text of picture descriptions will contain HTML markup.

What next? Well, as with many applications, the XML itself is of not much use by itself, so we need to extract something that can be used or displayed. To get a list of the item titles we can write:

Which is mostly self-explanatory; search-children returns an array of sadXMLNodes, and we need to check that the return from get-child is not null - note that the content of a node is obtained from sadXMLNode.text, which will be the empty string if there is no conent.

The walk-nodes method provides a more powerful mechanism for searching the tree and building sets of nodes. It takes an anonymous procedure as input - which is applied to all nodes in the tree; when the procedure returns true, the traversal of the hierarchy is stopped. For the simple case of getting picture titles, we would use walk-nodes with a procedure as follows:

For the simple search walk-nodes provides no advantages, but it is useful for more complex searches - for example finding all nodes that have an attribute with a specified name or value.

So that's the 10 cent tour. Use the sadXMLParser and sadXMLNode classes to transform your XML into a tree of nodes, and use the node search methods to extract the data you need from the XML.

Next to come, we'll show the use of the sadXMLHttpRequest to build a simple RSS viewer.

First, some background for the newcomer - if this is old news you can skip this primer and go straight to the details below the fold. This started with the need for an MD5 implmentation for the Flickr api. MD5 is the acronym for Message Digest alogrithm 5, which is a 128-bit cryptographic hash function defined in RFC1321.

A hash function produces a fixed-length string - called a message digest - from a string (message) of any length; the hash function produces a very different message digest as the result of a small change in the message. There are several families of algrorithm for calculating a digest, and the vulnerability of the produced digest to a security attack is essentially related to its length - in FIPS 180 the number of security bits is half the size of the digest. The MD5 digest is short enough to be attacked - and the SHA-1 algorithm of 160 bits is now considered vulnerable too. The SHA-2 functions produce longer digests, and the SHA-384 and SHA-512 handle longer message lengths too - up to 2^128 bits.

The MD5 hash function is used by the Flickr api to specify a signature for methods that require authentication. For a Flickr call, the signature is the MD5 digest of a string comprised of the method parameters and the shared secret for the api key issued for the application.

This is a typical use of a hash function - creating a digital signature from a key to verify the authenticity of the message; the recipient of the signature can confirm that it was built from the key by recreating the signature using the same function. Similarly, the integrity of a file's contents can be verified by generating and comparing a message digest of a checksum for the file.

Related to this use of hash functions are Message Authentication Codes (MACs). A MAC is generated from a secret key and the (abitrarily long) message to be authenticated. The keyed-hash message authentication code (HMAC) uses a hash function and a key in the algortihm described in FIPS PUB 198 and RFC 2104 . The construction of the HMAC iteratively compresses blocks of the message and makes a digest of them.

As announced earlier, the COM.CURLR.CRYPTO package implements the hash functions for MD5 and the SHA-1 and SH-2 algorithms, and the HMAC functions for these. Read on for notes on their usage.

The COM.CURLR.CRYPTO hash functions are implemented using the class structure of Curl's MSgDigester and MsgDigest base classes. The follwing code shows how to create the MD5 message digest for a string "abc", and how to create it when reading from a file and when writing to a file:

The class structure for each hash function is the same, so you would just replace the MD5 with SHA-1 etc.. to have the equivalent code for the other algorithms. (For usage consistency, there's an implementation of SHA-1 in the package - but obviously you can use the digester supplied in the Curl product). Clearly, you would need to add your own error handling on the file i/o, and consider such niceties as character encoding to use this in an application.

The HMAC functions are simple to use as well, but require a little more thought about what is being hashed - for example, the test cases from RFC 2202 specify the key as a hex string. The curlr function digest-from-ByteVec takes ByteVecs not Strings as its arguments, and returns the digest as a ByteVec, which in the test is converted back to a hex string - note that the digest is also available as a field in the HMAC class, but its to-lower-String method will not give a hex string.

As an added extra, there are some useful byte and bitwise functions in the package, including bit rotations functions (bit-rol, bit-ror, bit64-rol, bit64-rol) and byte conversions (int32-to-ByteVec, ByteVec-to-int32, ByteVec-to-int64, ByteVec-from-hex-string, ByteVec-to-hex-string).

I've also implemented the pseudo random tests for the SHAVS testing, along with the HMACVS tests, so now COM.CURLR.CRYPTO passes all the pre-validation tests provided by NIST. This is for hashing whole bytes, so the bit tests will not be passed any time soon. The code and tests are all checked in at the curlr repository. The pcurl'd package is available at the curlr forum if you're a member, and will be posted on this site soon. Usage notes to follow later.]]> Curlr http://www.curlr.org/index.php?itemid=33 Mon, 21 Aug 2006 15:58:02 -0400 http://www.curlr.org/index.php?itemid=32 http://www.curlr.org/index.php?itemid=32 I've been distracted by implementing hashing algorithms. I've extended the COM.CURLR.CRYPTO package with classes for SHA-224 and SHA-256 (plus my own SHA-1 for consistency) hashing algorithms. And I've included classes for creating HMACs (keyed-hash message authentication codes) for all these and for MD5.

The Security Hash Standards (SHS) are comprehensively documented in FIPS PUB 180-2, which you can find at NIST, along with much else concerning cryptographic standards. There's a validation standard too, and though I don't think I'll get the code certified, the implementations do pass the sample tests for byte implementations. I've included those tests in the curlr repository - with the caveat that the data files are from NIST, not me.

The code is to be found in the curlr repository which is open for downloads - but not yet for modification of the source. The source is a little rough, but it passes the basic set of tests, and my Flickr api seems to work correctly when using it. You can try it out (if creating MD5 hashes is your idea of fun) here.

The MD5 code is probably more widely useful than in just the Flickr api, so it resides in a crypto package, with the intent that other useful implementations will live there too - the package is COM.CURLR.CRYPTO. The code is an implementation of the Curl base classes MsgDigest and MsgDigester, and provides similar functions to the native SHA-1 digests. I've also included implementations of MD5-ByteOutputStream and MD5-ByteInputStream to build digests for ouput and input streams - though I've not tested these yet.

I've added a couple of utility methods, so it's simple enough to use the digest as a lower or uper-case string. Note the naming convention; class names are prefixed sad, partly to singify my authorship but mostly to distinguish these implementations from any other Curl versions.

The one issue I know of so far is that the method MD5-Digest.to-base64-String blows up becaase of a bug in the Curl base class- so don't use it, and use to-lower-String instead.

The main idea has been that there is a separate class for each Flickr method, with the intent that a single object handles the call and the interpretation of the response. Using the Curl IDE we get the bonus of auto-completion for the arguments of the request method, so the basic programming is straight forward enough with the api decribed previously. But there are 88 classes, and they all have very similar constructor signatures - requiring the secret and api_key. It will get to be tedious having to type these values in more than once, and a programm may well need to set / reset the authorization token on many of these objects. There may be other tasks that require handling all of the constructed API objects, so we need an organizing entity to make life a little easier.

The shape of an organizing class is simple, once we know what it is that we need. The base class can be generated by the build process - ensuring that it is complete - and looks like this:

I've shown the pattern for only the authorization methods, but it's identical for all the other methods. So for a very small startup oveherhead, a BaseFlickrAPI object creates instances of each of the methods and stores them in a HashTable. The setter code for the auth_token shows how this is used to perform global assignments.

It isn't my intention that BaseFlickrAPI is used directly in an application - we'll actually be using a subclass - if it was, a request might look like this:

The class helps organize the methods, and is useful for implementing higher level functionality.

I started to build a rules engine with the hope of playing with different combinations of behavior, but didn't get further than what you see. Get started by adding a shoal - just click the add button. The fish will swim around the tank avoiding each other and the tank walls, but will also try to keep together.

The display is a scaled 3D scene of a 1m cube tank;it's interactive in that you can move your view around the wireframe "tank" by moving the mouse while holding down the left button. And you can zoom in and out by holding down the right mouse button and moving the mouse. Other than that, the control box is pretty obvious - except the parameters actually used are distributed around the values you specify according to the variation factor. This is mostly so that the fish appear with a range of sizes. I'll post the code soon.

It's not very efficient, so expect to see your cpu usage go way up, especially if there are large shoals. But with a high frame rate and the right combination of values you can pursuade yourself that the fish are actually swimming around!

This is a combination of some photo utilities using the Curlr api. This is an embedded applet so you will need to first click on the box to activate it. If you prefer, you can run the app in its own browser, and then you won't have to do anything. More interestingly, if you're using IE you can run it as a standalone applet.

It's simple to use - and more features will be added. Navigate using the prev, next and arrow buttons - all of which do the obvious thing - and have tooltips to prove it. The numbers are indexes of photos andl the indexed photo will be displayed when you click on them.