Chapter 12: Sharing Photos with Hilo
In this chapter, we’ll describe how the Hilo applications have been extended to allow you to share photos via an online photo sharing site. To do this, Hilo uses the Windows 7 Web Services application programming Interface (WSSAPI). The Hilo Browser application has also been updated to provide additional user interface (UI) and touch screen features, and the Hilo Annotator application has been extended to support Windows 7 Taskbar Jump Lists. You can download the final version of the Hilo source code from here. This chapter provides an overview of these new features.
Updating the Hilo Browser User Interface
Hilo’s photo sharing functionality is accessed through the Hilo Browser application. Previous versions of the Hilo Browser allowed the user to launch the Annotator by double-tapping (or double-clicking) a photo in the media pane. This worked adequately because there was just one action that could be performed on a photo. Now that there is an additional action—share—another approach must be used. In the final version of the Hilo Browser, double-tapping a photo shows the photo in the slideshow mode (Figure 1) while double-tapping the screen again returns to browsing mode.
Figure 1 Using the slide show mode
.png "Gg241211.674e9ac2-0700-4599-be6b-ba52d33c0444-thumb(en-us,MSDN.10).png")
In slideshow mode, the carousel disappears and the selected photo is maximized to fill the window. Only one photo is shown in slideshow mode. Arrows are shown on either side of the photo to allow you to pan to the photo to the left or right. On a touch screen you can also touch the photo and, with your finger still on the image, flick it left or right to scroll in that direction. This is known as a touch screen gesture. The Hilo Browser supports two types of gestures: pan (the flick gesture to change photo) and zoom.
Figure 2 Resizing a photo with the zoom gesture
.jpeg "Gg241211.68721056-c2a5-416b-9371-2a2f2f282a1a-thumb(en-us,MSDN.10).png")
The zoom gesture requires two fingers (Figure 2) touching the screen. When you move your fingers apart to zoom in, the image size increases, and when you move your fingers together to zoom out, the image size decreases. Gestures like this can make an application feel more natural to use.
Figure 3 The Share and Annotate Buttons in the Hilo Browser
.png "Gg241211.7d065412-2fac-4e4f-abd6-49de01fbb2f1-thumb(en-us,MSDN.10).png")
The Hilo Browser, in browsing mode, now also provides two buttons in the top right corner, as shown in Figure 3. These buttons allow you to launch the Annotator application, or to share the selected photos via an online photo sharing site. These buttons display images to illustrate their purpose: the Share button has an arrow directing the movement of the photo document to the globe representing the Internet; the Annotator button has a photo and a pencil. Normally these buttons do not have captions, but when you hover the mouse cursor over a button, the button edge is highlighted and the caption appears beneath the button.
Using Taskbar Jump Lists
The final version of the Hilo Annotator application adds support for Windows 7 Taskbar Jump Lists, which allows you to easily access previously edited photos and to initiate important tasks directly from the taskbar. In order to uses these features, however, your application will have to be registered with the Windows shell. Hilo provides a utility application to help with this process.
When the Annotator first runs (for example, in response to you clicking on the Annotator button in the Browser) it checks to see if the application is registered and if not, it runs a utility called RegistrationHelper. This is a once-only action. RegistrationHelper is a console application and it needs Administrator privileges to run. If your account does not have these privileges then you will get an error message. Even if you run RegistrationHelper as Administrator you will get a User Access Control message asking you if the utility should be given permission to run (click Yes). After running the registration helper utility, it will inform you if the action was successful (Figure 4). From this point onwards, the Hilo Annotator application can display the Recent files Jump Lists on its Taskbar.
Figure 4 Successful registration
.png "Gg241211.acc28013-6851-4faf-a3bb-8322c15db313-thumb(en-us,MSDN.10).png")
The utility can also be used to unregister Annotator, for example if you want to remove Hilo from your computer. The command line help is shown in Listing 1. You have to provide at least six command line parameters. The first parameter determines whether you wish to register or unregister the application (use the string TRUE or FALSE). The next parameter is a ProgID (for Annotator use Microsoft.Hilo.AnnotatorProgID) and the utility will either add or remove this key from the HKEY_CLASSES_ROOT registry hive. The next three parameters are only needed if you are registering Annotator. The third parameter is the full path to the Annotator application, the fourth is the name that will be used to identify that a file type is edited by Annotator and the fifth parameter is an identifier called an application user model ID, which is essentially used to group together icons for an application as a single button on the taskbar (for Annotator use Microsoft.Hilo.Annotator). The remaining command line parameters are the extensions of the file types that Annotator will edit.
Listing 1 Command line options for RegistrationHelper.exe
Usage: RegistrationHelper <Register:TRUE|FALSE> <ProgID> <FullPath><FriendlyDocumentName> <AppUserModelId> <ext1,ext2,ext3,...>
If you wish to unregister the application then you must provide the ProgID and the file extensions, but you can provide empty strings for the other parameters, this is shown in Listing 2, where empty strings (“”) are given for the path, the friendly name and the AppUserModelID parameter.
Listing 2 Unregistering Annotator
RegistrationHelper FALSE Microsoft.Hilo.AnnotatorProgID "" "" "" .bmp .dib .jpg .jpeg .jpe .jfif .gif .tif .tiff .png
The registration utility adds values to the registry to indicate that the Annotator application may be used to open files of the specified types. In addition, the registration associates the ProgID with the file type and since the ProgID is associated with the application user model ID this indicates to Windows 7 that these files can be edited by Annotator and can be shown on Annotator’s Jump List.
There are two Recent Item lists that are relevant to Annotator. The first is the Start menu Recent Items list (Figure 5). If you do not see the Recent Items list on your Start menu, you can enable this feature through the Start menu properties. The Recent Items list shows the recent files for all applications. In Figure 5 the two recent items are image files that were edited with Annotator.
Figure 5 Showing the Start Menu Recent Items list
.png "Gg241211.eae8ae63-2ae1-4903-8627-e0dd509a7724(en-us,MSDN.10).png")
Each application can have a Recent files Jump List. Figure 6 shows the Jump List for the Annotator application which is displayed when you right-click the Windows 7 Taskbar button for Annotator, or with the touch screen when you touch the taskbar button with one finger and with your finger in place tap the screen with another finger. The bottom three items are standard for all application Jump Lists and are task items that allow you to start a new instance of the application, pin the icon to the taskbar, or close the specific window. The top part of the Jump List shows the files that have recently been edited with Annotator.
Figure 6 Showing the Jump List for Annotator
.png "Gg241211.95882943-8152-4e47-ba50-666518fa6a0c(en-us,MSDN.10).png")
If you compare Figure 5 with Figure 6 you can see that the files added to the Annotator Recent file list are added to the Start menu Recent Items list. When Annotator adds a file to the Recent file list it associates the file with the application user model ID (often abbreviated as AppID, but this is not the same as the GUID used by processes to specify DCOM parameters). The AppID allows the icons of multiple instances of the same application to be grouped together on the taskbar, however if you choose you can give different instances different AppIDs to provide separate icons on the taskbar for each different AppID.
When you click on an item in the Recent file list, Windows 7 locates the ProgID for the AppID for the button, and uses the open verb defined in the ProgID to start a new instance of the application with the item. If instead, you right-click the item you’ll get a context menu which includes the option to view the property page for the item, Figure 7. This shows that the file type (the friendly type name) is Microsoft Hilo Annotator, rather than a generic description of the image type. The important point is that this file type is displayed only when the properties dialog is accessed through the Annotator Jump List. If the file’s properties are shown through Windows Explorer then the default file type will be displayed.
Figure 7 Property page for an item on the Annotator Jump List
.png "Gg241211.1a68abcd-242d-45bf-85f0-08ea43c9b5f0-thumb(en-us,MSDN.10).png")
The Recent file list is one of the standard categories that you can use on an application’s Jump List. Figure 6 shows the standard tasks that are appended to all Jump Lists. You can add custom tasks and Browser adds a custom task to launch Annotator, Figure 8. In this case the task is a shell link object that starts the Annotator process.
Figure 8 Browser custom task list
.png "Gg241211.79024d32-1e0c-4caa-807a-7e00c99b47fe(en-us,MSDN.10).png")
In Windows 7 the default action of hovering the mouse over (or holding your finger on) a taskbar button gives a thumbnail image of the application’s window but developers can customize this view and even add controls to it. Hilo Annotator implements a custom preview window, as illustrated in Figure 9. The Annotator does two things: first it provides a preview of the selected photo, and second it provides two buttons which you can click to change the thumbnail (and the image in Annotator) with the image to the left or right.
Figure 9 Annotator task bar preview
.png "Gg241211.7d27b0d7-eea0-4a5e-851c-9aaf3e73ddef(en-us,MSDN.10).png")
Sharing Photos on Flickr
The Hilo Browser allows you to share photos through Flickr—a popular internet photo sharing site that implements a Web Service API to allow photos to be published programmatically. The Hilo Browser uses the Windows 7 Web Services Application Programming Interface (WWSAPI) to access the Flickr API to authenticate a user and to upload a photo to the user’s photostream.
In order for any application to be able to upload photos to Flickr, it must first be registered with Flickr. Flickr then issues a two part Flickr API Key. One part of this key is used to identify the application, while the other part is used to sign and authenticate the data that it passes through the Flickr API. The Hilo Browser application passes this key to Flickr whenever it performs an action against the Flickr API.
Once the Hilo application has been registered with Flickr, it can be used by any user to upload photos to their account. To enable this, however, the user has to specifically authorize the Hilo application so that it can access their account. Issuing a Flickr API Key means that Flickr knows about and trusts the Hilo application. But individual users then have to choose whether or not to trust the Hilo application.
Obtaining a Flickr API Key
The Hilo Browser source code does not include a Flickr API key. You will need to obtain a key yourself and add it to the Hilo Browser source code before it can interact with the Flickr API. You can apply for an API key through the Flickr services website.
You can use any Flickr account to obtain a Flickr API Key for Hilo. If you don’t already have a Flickr account, you first have to create a Yahoo account, log in ,and then follow the steps to create a Flickr account. Once you have created a Flickr account you can then apply for an API key. There are two options: a key for commercial applications, or one for non-commercial applications. To test out Hilo, you should apply for a non-commercial key. This will result in a web page similar to Figure 10, where you are asked to provide information about your application.
Figure 10 Applying for a Flickr API key
.png "Gg241211.ab0eb745-8626-4b91-8092-0bfa280fe5d6-thumb(en-us,MSDN.10).png")
Flickr will then provide you with two strings (Figure 11), one is the API key that uniquely identifies the application (Hilo in this case), and the other string is a shared secret string that Hilo will use to sign data sent to Flickr. This enables Flickr to verify the integrity of the parameters passed to it. You should make a note of the API key and secret strings because you will need to add them to the Hilo Browser source code, as described in the next section.
Figure 11 Obtaining the API key for Flickr
.png "Gg241211.d1ef5a7d-d1e9-4c68-b914-357e10d625fb-thumb(en-us,MSDN.10).png")
Adding the API Key to the Hilo Browser
The Flickr API key identifies the Hilo Browser application to Flickr. It is defined directly in the Hilo Browser’s source code so that it can be easily accessed and used whenever a photo is uploaded. Once you have obtained a Flickr API key, you will need to add the two strings to the Hilo Browser source code. To do this open the FlickrUploader.cpp file in Visual Studio 2010 and search for the two lines shown in Listing 3. Paste the strings for the Flickr API key and secret into these two variables.
Note
Storing cryptographic secrets clear text in a code file is NOT recommended for production code. Hackers can simply scan the executable and obtain the key. However, since the purpose of Hilo is to illustrate how to access a Web Service, rather than to illustrate cryptography, the simple (though unsecure) approach is used.
Listing 3 Providing Hilo access to the Flickr API Key
static wchar_t* flickr_api_key = L"";
static wchar_t* flickr_secret = L"";
Sharing a Photo using the Hilo Browser
Once you have recompiled the Hilo Browser application you will be able to upload photos to Flickr. To do this, select a photo in the media pane and touch (or click) the Share button. This will launch the Share dialog shown in Figure 12. This dialog allows you to determine if a single file, or all files in the folder, are uploaded and it allows you to select the photo sharing service that will be used (only Flickr is supported at the moment).
Figure 12 Sharing a photo through Flickr
.png "Gg241211.b46b7a00-5958-45f2-9ea7-f3a872719a77-thumb(en-us,MSDN.10).png")
Hilo will upload photos to your account once you acknowledge that Hilo has permission to do this. Once you click the Upload button on the Share dialog you will see the authorization dialog, Figure 13, requesting that you authorize Hilo.
Figure 13 Authorizing Hilo to upload to your Flickr account
.png "Gg241211.dc713c86-06ab-4b18-a1d2-237dc7d777a8-thumb(en-us,MSDN.10).png")
When you click the Authorize button Hilo launches your browser and opens the Flickr web page to authorize Hilo. The URL of this web page identifies Hilo by providing the API Key as one of the URL’s GET parameters. If you are not logged in to Flickr you will be requested to login in before the authorization web page is shown, Figure 14. This page says that photos will be uploaded to your Flickr account , but before this can be done this account must authorize Hilo.
Figure 14 Authorizing Hilo
.png "Gg241211.536fa563-e0d9-4a00-8546-5b30b995c711-thumb(en-us,MSDN.10).png")
There is no authorization callback to Hilo, so if you decide not to authorize Hilo to access your Flickr account Hilo will only find out is when it attempts to upload a photo and the access fails. So regardless of which button you click on the web page shown in Figure 14 you will see the confirmation dialog, Figure 15, which is used simply to block Hilo from uploading until authorization is complete.
Figure 15 Confirming authorization
.png "Gg241211.9514d76c-7a8a-47f6-a87c-f0bafe688624-thumb(en-us,MSDN.10).png")
When you click the Authorization Complete button and the Flickr account has authorized Hilo, the upload process starts and progress is shown using the dialog shown in Figure 16. When the upload is complete you will see a message and a link to view the photos that you have uploaded as shown in Figure 17.
Figure 16 Uploading the photo
.png "Gg241211.b7abe6fb-d82c-4fbe-b706-07b95c4d958a-thumb(en-us,MSDN.10).png")
Figure 17 Photo upload finished
.png "Gg241211.cf7bf14f-ae8c-4f99-a5eb-0b926e666aec-thumb(en-us,MSDN.10).png")
The URL link is to the Flickr page which allows you to add a description and tags for the photo, Figure 18.
Figure 18 Uploaded photo web page
.png "Gg241211.14f6430a-4e4e-4fd1-a142-aa992baa0a02-thumb(en-us,MSDN.10).png")
Conclusion
The final versions of the Hilo applications add some additional UI features and the ability to upload photos to the Flickr photo sharing website. The Hilo Browser now supports touch screen gestures to pan and zoom photos, while the Hilo Annotator now provides Jump Lists to give quick access to recently edited files and key tasks. The Hilo Browser contains the code to upload photos to Flickr via the Flickr API web service. In the next chapter we’ll cover the implementation of the user interface features in more detail.