In this second post on the topic we will focus on the client side desktop app that will be in charge of creating the requests using the web service published API. This desktop app will send new data to our web server app so it can be added to the backend database.

The main topics are:

• Creating a subclass from the URLConnection class
• Dealing with the data received from the server as result for the request
• Encoding a JSONItem for sending data to the web service

As stated in the previous entry, the example doesn’t include the normal (and recommended) verifications on the data provided and received or the check on possible errors; we are only focused on the main topic.

Creating an URLConnection subclass

Let’s start by creating a new desktop project. Add a new Class using Insert > Class and use the Inspector to assign URLConnection as the Super Data Type as shown in the picture:

With the just added class still selected in the Navigator (the leftmost column in the IDE Window), add a new property to it (Insert > Property). We will use this property so it points to a DesktopListBox in our user interface, and so we can update it with the data received from our web service. With the just added property still selected, use the Inspector to set its Data Type and Name (text label used from our code to refer to such property) as follows:

• Name: List
• Type: DesktopListBox
• Scope: Private

Note that we set the scope as Private. This means that this property can be accessed only from the instances of the class, and not those that are created from other data types or even those created as subclasses from this class.

URLConnection: Asynchronous communications

Why would we want to maintain a reference to a ListBox control in our URLConnection class? As with any kind of problem, we can take several approaches in order to solve it. In this case, is a very convenient way to get a reference to the control we want to update as we will be using the URLConnection asynchronously.

Once we call the request against our web service, the execution of the app will not be paused until we receive a response, this allows the user to do other operations if they want. In this case the class instance, via the ContentReceived event, will be responsible to receive the new data from the web service, so we can use it.

In fact, this is our next step. With our URLConnection subclass still selected in the Navigator, add a new Event Handler to it (Insert > Event Handler…). In the resulting window, choose the PageReceived option from the list and confirm the selection, so the event will be added to the class under the Event Handlers section.

Now, with the just added Event Handler still selected, write the following snippet of code in the associated Code Editor:

#Pragma Unused url

If HTTPStatus = 200 Then // We received an OK as the status for our request
  If Content.Length <> 0 Then // And we have data to process as part of the reply
    List.RemoveAllRows // So we delete previous existing entries in the associated ListBox Control
    content = content.DefineEncoding(Encodings.UTF8) // We set the encoding for the received data
    
    Var items As Dictionary = ParseJSON(content) // And proceed to create a new dictionary from the received data in JSON format
    items = items.Value("AllAlbums") // We get all the items for the key 'AllAlbums'…
    For Each item As DictionaryEntry In items // …iterating on them…
      Dim tempDict As Dictionary = item.Value // …and retrieving the dictionary (JSON item) for it…
      Dim title As String = tempDict.Value("title") // …so we finally access the desired value
      list.AddRow title
    Next
  End If
End If

The code is commented so you can follow what happens in each line in the process; but it is worth it to point out that the ContentReceived event gives us all the parameters we need in order to work with the data sent from the web service:

• URL: The URL returned as the reply for our request
• HTTPStatus: The HTTP status code that you should read to verify the success of the request
• Content: This is a String that can contain the data associated with the reply.

In addition, you can also add an extra event handler to our subclass: Error. This will be fired when an error is produced while dealing with requests sent from the instance.

With the events and property already set, it is time to add a couple of methods in charge of commanding our URLConnection subclass to launch the requests. For our example, those method names are directly related to the operations we want to do on the web service API created on the first part of this tutorial.

So, with our URLConnection class still selected in the Navigator, add a new method (Insert > Method), using the following data in the associated Inspector. This is the method in charge of requesting our web service for the name of all the available albums. Of course, we expect to receive the reply through the ContentReceived event:

• Method Name: GetRequest
• Parameters: theList As DesktopListBox, theURL as String
• Scope: Public

As you can see, this method expects to receive the reference to a DesktopoListBox control, and the text to the URL that should be the end point of our web service. Now put the following code in the associated Code Editor for the just added Method:

List = theList
self.send("GET", theURL)

Simple, isn’t? As you can see, we save the reference to the DesktopListBox control in the instance property so we can use it later for updating its contents with the received data. Then we use the Send method from the class with the GET verb and the URL where our web service should be listening for incoming requests. As previously stated, this is an async operation, so we will let our object to react through the ContentReceived or Error events.

URLConnection: Sending data as part of a request

Add a new method to the subclass, using the following values in the resulting Inspector. This is the method allowing us to send data to the web service so they can be added to the backend database:

• Method Name: SendItem
• Parameters: Item As JSONItem, theURL As String
• Scope: Public

This time, the method expects to receive and JSONItem object (pointed via the variable Item) and a String instance that should be the web service endpoint URL. Put the following code in the associated Code Editor for the method:

Self.SetRequestContent( item.ToString, "application/json" )
self.Send("POST", theURL)

The URLConnection instances allow us to associate additional information (data) for a request sending, in addition to those added through the HTTP headers (Head), using for that the SetRequestContent method. This method expects two parameters: a String with the real data to attach, and the definition of the type of data we are sending (this is, the MIME Type) as a String instance.

Finally, we launch the request in the second line of code, using for that the URL assigned to the theURL parameter and using the verb POST.

Designing the User Interface

We have already finished all the logic behind our example app, via our URLConnection subclass. So now it’s time to design a minimal user interface so we can verify the correct functionality of our client agains the web service.

Select the Window1 object and add the required control so it looks like the one displayed here (from top to bottom): a DesktopListBox, a couple of DesktopTextFields in addition of two DesktopLabels, and two DesktopPushButtons named “Request” and “Send”.

Next, add an instance of the created URLConnection subclass. For that, simply drag the created subclass from the Project Browser to the Window Layout Editor and a new instance will be added to the Tray in the lower section of the Editor, as shown in the following picture:

The only code present in the user interface is the one that we will add to both PushButtons. Double click the one labeled “Request”, and add the following line of code to its Pressed Event Handler:

MyConnection1.getRequest(AlbumListbox, "http://127.0.0.1:8081/GetAll")

It calls the getRequest method on the instance based on our subclass, sending as parameters the control “ListBox1” and the text for the (local) URL where the web service should be listening.

Double click the PushButton labeled “Send” in order to add the Pressed Event Handler and write the following fragment of code into the associated Code Editor:

Var d As New Dictionary
d.Value("Title") = TitleField.Text
d.value("ArtistId") = ArtistIDField.Text
Var item As New JSONItem
item.Value("newAlbum") = d

MyConnection1.sendItem(item,"http://127.0.0.1:8081/AddAlbum")

As you can see, there is nothing magic in it. We simply create a new dictionary using the keys expected from our web server to access the underlaying data for the record. In addition, you can see how easy it is to create a new JSONItem from a Dictionary!

Then, we simply call the sendItem method on our URLConnection subclass instance, passing along the expected parameters: a JSONItem instance and the web service endpoint URL that should include the method we want to call in the remote API.

Ready to listen for your requests!

We have finished our client app! Launch the web service created in the first part of the tutorial (make sure it is listening using the port 8081). Then, run the desktop client app and push the buttons for “sending” or “requesting” the information. You will see how with the request you’ll receive all the albums available in the example database, while with the “Send” button you’ll be able to add new records to the database with the data provided in both TextFields.

In conclusion, Xojo allows us to create both the backend and the multiplatform clients in record time and in a really easy way! Obviously, the examples used in these two articles are not, by far, complete solutions you can use “As Is”, but they give the basics you can use to construct more robust and complete solutions for your own needs.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others

*Read this post in Spanish

If you were at XDC 2018 maybe you caught my iOS session where I showed how to send an update to the App Store. The app I updated was Cats Up!, a simple iOS app that display cat pictures. Dogs Up! is the dog version and it uses the Dog API.

To make this app, I made a copy of the Cats Up! project and then started changing the parts necessary to hook it up to the Dog API. Changing existing projects is a great way to learn and one of the reasons we are doing the Just Code Challenge.

The Cats Up! project used a single HTTPSocket to connect to its web service for the cat pictures. The Dog API required two HTTPSockets: one to request a URL to a dog picture and another to download the picture itself.

Once these steps were done, I just needed to update the JSON file with dog facts (instead of cat facts), find something to use for the dog icon and get a recording of a dog bark to use when a new picture is displayed.

Download the Dogs Up! project.

Download and check out earlier projects:

• Week 2: Password Generator
• Week 1: Color Picker

After a bit of experimentation this January we were able to isolate one huge cause of this annoying behavior. Unfortunately it has to do with a misconfigured IPv6 DNS server configuration and whether or not yours is correct may be up to your service provider.

Whose bug is this?

According to the spec, IPv6 DNS servers are supposed to return immediately if they can’t fulfill the request. Unfortunately this is almost the exact opposite of what an IPv4 DNS server does, in that it may forward your request to the next server to see if it knows where your request should go. Unfortunately we found that only about two-thirds of the ones we tested were correctly configured.

On macOS and Linux, DNS requests are sent concurrently, that is, two requests are sent at the same time, one each for IPv4 and IPv6. The one that returns first is used. On Windows, the requests are unfortunately sent sequentially, IPv6 and then IPv4. What this means is that IPv6 requests just hang there, waiting for a response that will either never come or will wait until the underlying socket reaches its timeout. When that fails, the IPv4 request is sent and fulfilled and your socket request goes through.

What To Do

Here are a few things you can do to test this theory. While you can’t really ask all of your users to do this, it will tell you if this is where the problem lies.

1. Turn off IPv6.
   1. Click Start and then Settings.
   2. Search for Network Connections.
   3. Click View network connections.
   4. Right-click on the active connection and select Properties.
   5. On the Networking tab, clear the Internet Protocol Version 6 (TCP/IPv6) check box, and then click OK.
2. Change the DNS entries for IPv6 from the defaults to point to Google Public DNS or OpenDNS.
3. Make a Hosts file entry. If your installer runs as an administrator, you can make an entry in the hosts file to force the computer to use IPv4. This is not a long term solution as the world moves to IPv6.The hosts file on Windows 7/8/10 is located at:

   C:\Windows\System32\drivers\etc

   and you should add an entry which looks like this:

   Server IP Address<TAB>domain name

4. If it’s a domain that you control, make sure you only use IPv4 DNS entries and that your server is only listening on the IPv4 interface.

All in all, it’s a frustrating problem. While there’s no easy solution, the good news is that because there are no IPv4 addresses left to be distributed, the world is moving to IPv6. The more demand there is, the more likely that the incorrect DNS servers will get fixed because they’ll cause problems for other sites as well.

In addition, we will also use the Declare statement to access the iOS Clipboard so we can Copy the shortened URL in order to use it in any other app installed on the device.

Before you can start with this tutorial, make sure you have installed Xcode on your Mac. You’ll need the Simulator app, included with Xcode, in order to run any iOS app developed with Xojo (you can download and install Xcode for free from the Mac App Store). You will need also a General OAuth key to use when accessing the Bit.ly’s API exposed methods. To get your own key, you have to create an account on Bit.ly and follow the instructions found here.

Of course, to follow this tutorial you also need to install Xojo on your Mac! You can always download the most recent release of Xojo from here.

Designing the interface

Run the Xojo IDE and select the iOS App template from the Project Chooser. As result, the IDE will create a new project that already includes the barebones items in order to have a functional App. In fact, clicking the Run button will launch the app on the Xcode’s Simulator showing the default View… but nothing else.

Choose the View1 item on the Navigator (the leftmost column on the IDE). This action will show the project default view on the Layout Editor. Click on the Library button and you will see all the objects or graphic components (UI elements) available for you to design the user interface for your iOS apps, as shown in this picture.

Drag the TextField control from the Library (found below the Inputs group) and drop it on the upper side of the view. Use the control handlers and the alignment guides to adjust his position and size, as shown in the following picture.

Select the just added TextField and click on the Inspector button in order to change some properties for the control. Here is the place where you can change some attributes like the control’s name (the one used to refer the control from code), the text color, keyboard type, text alignment, font size, etc. In this case, we will change these properties:

• Name: txtURL
• KeyboardType: URL
• PlaceHolder: http://
• Text: http://

Once done, drag a Button from the Library and place it to the right of the TextField added before. Use the control handlers to adjust their size, and push on the icon with the picture of a pencil to change the label text to “Go!”, as shown in this picture.

Besides shortening the typed URL, our iOS App will also show the corresponding webpage for that URL, something as easy as placing a HTMLViewer control instance from the Library below the TextField, as shown in the following picture.

Finally, we will add a couple of Label controls below the HTMLViewer and a second Button control. The leftmost Label control will be a simple… well… label, but the second one will reflect the shortened URL. Place these controls from the Library, adjusting their sizes and positions as shown in this picture.

Choose the central Label, the one used to show the shortened URL, and these properties, with the help of the Inspector:

• Name: lblShortURL
• Text: (vacío)

We finished our User Interface design! (tough?) In fact, you can again click the Run button from the Xojo IDE in order to run the app on the iOS Simulator. Once again, our default View will show up and, this time, you can play with the TextField and the Buttons… but nothing will happen yet. This is normal, we have to put the code on these controls we want to execute as a reaction to some kind of user interaction (event).

Return to the Xojo IDE, stop the app execution (click on the Stop button) and change your interface designer hat with the programmer one. Yeah, it’s time to write our own subclass in charge of communicate with the Bit.ly API!

Talking with Bit.ly’s API

It’s time to write our communication class with the Bit.ly’s API. That’s the class responsible of making the web request (via HTTP protocol) to the exposed method by the remote API…and to receive and work with the returned data. And, when it comes with web communications where we have to asynchronously deal with the received answer, we have to use our inherited subclass from Xojo.Net.HTTPSocket in order to add the specialized behaviour over the one found on the base class.

Choose Insert > Class to add a new Class to the project. Click on the just added class on the Navigator and change these attributes on the Inspector:

• Name: BITLYSocket
• Super: Xojo.Net.HTTPSocket

Click now the ‘+’ button on the IDE toolbar and choose the Event Handler menu option, as shown in this picture:

Select the PageReceived event on the resulting Window and click the Ok button. This action will add the event under the ‘Event Handlers’ hierarchy for our BITLYSocket class. In fact, this event will fire, executing the associated Xojo code, every time our socket receives data as result of our HTTP requests.

Type these lines of code in the Code Editor for the PageReceived event handler:

if HTTPStatus = 200 then
  dim data as Dictionary = xojo.data.ParseJSON( xojo.core.TextEncoding.UTF8.ConvertDataToText(content) )
  dim dataurl as Dictionary = data.Value( "data" )

  raiseevent URLShortened( dataurl.Value( "url" ) )
end if

As you can see, we check the returned Status Code to make sure that our request was properly processed (integer value 200). Next, we assign the result of parsing the returned data as a JSON structure to the ‘data’ variable, defined as a Dictionary type. (Xojo makes it really easy to interchange JSON and Dictionary structures/objects!)

The third line of code is the one in charge of creating the ‘dataurl’ Dictionary variable, and that will point to the Dictionary that really has the data we are interested in: the shortened URL. Finally, we raise a new event on our own class, passing the shortened url as Text.

You can find that the keys used in the Dictionary variables to retrieve the associated data, are the ones provided by Bit.ly in the response data, whose structure is documented and available on the Bit.ly’s API website.

To define a new event for our class, make sure that the BITLYSocket item is selected on the Navigator and click again on the ‘+’ button on the IDE Toolbar. This time, choose the ‘Event Definition’ menu option, as shown in this picture:

Unlike when we add a new Method to a class, the new event definition just allows us to write its signature; I mean, the event name and the parameters it will receive (if any) and/or the returned type (if proceed). After all, the code implementation for the event is a job of the Class consumer: the instances created from the class that decide to add the event.

As for our class, the added event will be responsible for passing the shortened URL to the class consumer (as we have seen in the previous code snippet), so the instance can decide what to do with the received data. In our app, this will be assigning the shortened URL (received as Text) to the central Label of our user interface.

Choose the added event and modify the following properties on the Inspector:

• Event Name: URLShortened
• Parameters: URL as Text

HTTP Request on iOS

With the BITLYSocket selected on the Navigator, we are going to add a new Method. This will be the entry point for the class consumer to pass the URL to be shortened. For that, click again on the ‘+’ button from the IDE toolbar and choose the Method menu option.

Type the following values on the associateed Inspector:

• Method Name: ShortURL
• Parameters: URL as Text

And type the following code on the Code Editor for the just added method (ShortURL):

Declare Function CFURLCreateStringByAddingPercentEscapes lib "Foundation" _
  (allocator as Ptr, origString as CFStringRef, charactersToLeaveUnescaped as CFStringRef, _
  legalURLCharactersToBeEscaped as cfStringRef, encoding as uint32) as CFStringRef

dim encodedURL as Text = CFURLCreateStringByAddingPercentEscapes(nil,url,nil,nil,&h08000100)

dim compossedURL as Text = "https://api-ssl.bitly.com/v3/shorten?access_token=" _
  + kToken + "&longUrl=" + encodedURL

me.Send("GET", compossedURL)

Here is where we find the first Declare statement on our code! In fact this one is responsible for calling the CFURLCreateStringByAddingPercentEscapes function in order to substitute the illegal characters on a URL with their hexadecimal values. This is done with the second line of code, where we call the function, assigning the result to the ‘encodedURL’ variable.

The third line of code is where we compose the final URL in order to call the Bit.ly API’s method, putting the OAuth key, present here as the kToken constant (define your own class constant, and assign your OAuth key to it), and also adding the variable that points to the URL, with all their characters correctly escaped, to the end of the string.

The last line of code is where we make the request itself, using the Send method from the HTTPSocket base class. The first parameter is the method we want to use for the request (“GET” in this case), and the second parameter is the URL for the HTTP request.

We have finished our class definition!

Putting all to work together

Let’s add an instance of our BITLYSocket class to the app. For that, select the View1 item from the Navigator and, then, drag the BITLYSocket from the Navigator over the lower part of the Layout Editor. This action will show the Shelf, where you can drop the item in order to create a new instance named BITLYSocket1 (this one will be shown also under the View1 hierarchy on the Navigator).

Select the BITLYSocket1 instance under the Controls section of View1 on the Navigator and add a new Event Handler. From the resulting window, you’ll see the event defined by us. Choose this event (URLShortened) and click the Ok button in order to add it to the BITLYSocket1 instance.

Type the following line of code in the associated Code Editor for the Event Handler:

lblShortURL.Text = url

This is the way we asign the received text (the shortened URL) to the Text property of the Label control instance.

But for this Event Handler to fire, we need to make the HTTP request in first place! Select the button Button1, add the Action Event Handler (the one that fires when the user pushes the button), and type the following code:

HTMLViewer1.LoadURL(txtURL.Text)
BITLYSocket1.shortURL(txtURL.Text)

Firstly, we load the web page for the URL typed on the TextField and, with the second line of code, we call the ShortURL method passing the URL as parameter. This line of code is what puts our communication socket to work!

Run again the app on the iOS Simulator and type some URLs. You’ll see that now the app load the corresponding webpage and shows the shortened URL on the lower label of the interface!

Basically, create a text file with the following content and drag the file over the Project Browser in order the Xojo IDE can merge it with the global Info.plist created during the app compilation:

<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE plist PUBLIC “-//Apple//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd“>
<plist version=”1.0”>
<dict>
<key>NSAppTransportSecurity</key>
<dict>
<!– Include to allow all connections; avoid if possible –>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
</dict>
</plist>

Copying to the Clipboard

There is one last detail: If you tap on the Copy button… it simply doesn’t work. We need to put some code here too inside the Action Event Handler.

Choose the Button2 item on the Project Browser and add the Action Event Handler. Type the following lines of code to the associated Code Editor:

declare sub setValue lib "UIKit" selector "setValue:forPasteboardType:" _
  (obj_id as ptr, value as ptr, pasteboardType as CFStringRef)
declare function generalPasteboard lib "UIKIt" selector "generalPasteboard" (clsRef as ptr) as ptr
declare function NSClassFromString lib "Foundation" (clsName as cfstringref) as ptr
declare function stringWithString lib "Foundation" selector "stringWithString:" _
  (clsRef as ptr, str as cfstringref) as ptr

setValue(generalPasteboard(NSClassFromString("UIPasteboard")), _
  stringWithString(NSClassFromString("NSString"), lblShortURL.Text), "public.text")

This is the solution that allows our app to copy the shortened URL text to the iOS Clipboard. This snippet of code has been extracted from this thread on the Xojo forums, showing once more how great is the Xojo’s community!

Now, every time you tap the Copy button you’ll find the shortened URL on the Clipboard.

In short, in this tutorial we have seen how easy it is to make Web API requests from our Xojo iOS Apps, work with the returned data as JSON, and how powerful and useful the Declare statement is, in order to work directly with the methods and functions from the Cocoa Touch and Foundation frameworks from our Xojo code.

You can watch the video (in Spanish only) that talks you though this example.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has used Xojo since 1998. He is in charge of AprendeXojo.com and the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app, among others.

*Read this post in Spanish

Communicating with web services is fun and easy with Xojo. But sometimes it’s not so easy to test the actual REST API calls. As part of preparing materials for the HTTPSocket webinar, I created a simple app in Xojo that lets you test REST APIs. I call it RESTy.

RESTy uses Xojo.Net.HTTPSocket to send a request to a web service and get a result. If the result is text (JSON, for example) it displays in the Response tab. Here, I am calling the Eddie’s Electronics web service to return a list of all the customers by specifying the URL and clicking the Fetch button:

For other data (binary data such as pictures) you can use the Fetch to File button to save the request to a file.

The Authentication tab is used to provide Basic Authentication should the web service require it.

The Request Content tab can be used to provide Content data that the request might need. For example, the Eddie’s Electronics web service also lets you request the details for a specific customer by providing simple JSON containing the customer ID. For example:

{"ID": 10039}

You can put this JSON in the Request Content tab and then call the web service to get the customer information using this URL (be sure to select POST as the method type):

http://demos.xojo.com/EEWS/index.cgi/special/GetCustomer

To be sure, RESTy is very simple, but you have the source code so feel free to add features to it!

• Download RESTy Project

If you’re looking for something with more features, there are also commercial products to test REST web services. Here are a few:

• Paw
• Do Http
• REST Scratchpad

If you know of others, let me know in the comments.

Want to learn more about Xojo.Net.HTTPSocket and web services?