Steves Code Corner

View iPod Nano songs without iTunes, C# Express, Part 5

2006-01-15T10:23:00.000-08:00

In the last post, we created the ITunesDBLib class library which allows us to retrieve information from the iTunesDB file and organize that information into useable objects. In this post we'll create the IPodBrowserExampleUI windows forms application, which will use the ITunesDBLib to display it's information to the user.

As with the last post, I won't go through each step to create and add the project to the solution. Instead we'll look at a screen shot of the project and it's classes, and discuss each class and key methods within it. Once again you are free to download the entire source here if you need more information.

Here is a screenshot of the solution with the IPodBrowserExampleUI project selected...

You'll notice that I expanded the References folder so we can see that we have a project reference to the ITunesDBLib. I also expanded the Resources folder since we are using some special icons I downloaded as part of registering my copy of C# Express.

The project itself really only contains two classes: Program and MainDisplay. MainDisplay is actually a partial class and it's two parts are defined in MainDisplay.cs and MainDisplay.Designer.cs. We'll go over these two partial classes in more detail in the next sections. If you are unfamiliar with partial classes however, you may want to check out this article for some background information first.

Program: This is the standard static starting class for a windows forms application. It contains the typical static Main() method that the application looks for when starting.

View Program Code (View)

There's nothing special to note here other than the fact that we are starting the MainDisplay form on the main thread.

MainDisplay (partial class located in the MainDisplay.Designer.cs file): This is the section of the MainDisplay partial class that defines the layout and display of controls on the form - basically the visual logic. Most of this code is autogenerated when you are working in the forms designer, so you should rarely need to come in here. However, I always like to see what Microsoft is doing behind the scenes. It's kind of like looking at your bank statement at the end of the month and saying "my wife spent $50 on what?".

View MainDisplay Code [partial] (View)

MainDisplay (public partial class located in the MainDisplay.cs file): This is the section of the partial class that contains the event logic for the form, and where the real code we need to implement resides.

View MainDisplay Code [public partial] (View)

There are several areas of note in this class, since this is where all the real code is placed. So lets start at the top.

One of the first things we do is declare an instance of the ITunesDBManager...

ITunesDBManager im = new ITunesDBManager();

The im variable can then be used throughout the class to retrieve data from it's underlying objects where necessary.

In the contructor of the class, you'll notice that after we initialize the components, we then run a conditional method called UseDebugPathToIPod. Basically, the purpose of this method is to find out if we are running this code in debug mode (determined by the [Conditional] attribute at run time. If we are, then this method will switch the drive letter of where the iPod is currently residing (typically F: drive). You'll recall that this application is designed to be deployed and run ON the iPod, so in a release version, this method will not be run, and we will use the Environment.CurrentDirectory instead. But during development, you should be testing your code locally (notice I said SHOULD be!).

Also in the constructor, you'll notice that we tie an event handler to the progressEvent event of the ITunesDBManager variable. This is so we can capture it's progress events and display them in a progress bar (I should note that the actual loading of data is so fast this event is not really needed atm, but if the lib were extended, load times could increase and this event might prove more valuable).

MainDisplay_Load: After the constructor, this is the next key method we need to look at. You'll notice that within it we call the LoadITunesDatabase method of the im variable, and pass in the path to the iTunesDB file. All we need to do from this side is figure out where the iTunesDB file is, and the im object will do the rest. Once the im variable has loaded the data and created it's internal objects, we can then get the entire collection of MHIT objects (aka tracks) using the im's TrackList method. We then pass this collection to the LoadTrackList method, which is discussed next.

LoadTrackList: This method is responsible for loading the songs into our grid. It accepts a collection of MHIT objects, and adds the song information to the grid using ListViewItems and their ListViewSubItems. We call the MHIT objects various Get methods (GetAlbum, GetTitle, etc...) to get information from it's underlying MHODString objects, and use those values to populate the list items. Note that the location to the song file is also stored in the tag property (this location does not include the drive letter!).

So that's pretty much all that happens when the form loads. The ITunesDBManager loads the data we need, and we populate our list of songs using the collection of MHIT objects within it. Now that we have our list displayed, we can cover the playing and extracting of song methods.

PlaySongMenuButton_Click: In this event method we allow the user to play a song currently selected in the grid. Basically we get the song subfolder location using the tag property, and then prepend the drive letter to where the subfolder is located on the iPod. Once we have this complete path, we create an instance of the Process object, and tell it to run the file. The Process object basically asks windows to look at the file and use whatever default program it has associated with that file type to open it.

ExtractSongMenuButton_Click: In this event handler method we allow the user to extract the currently selected song(s) from the list to a target folder they specify. Since several files could be selected and this could be a lengthy operation, we make the button itself checkable, and can therefore allow users to cancel a copy operation by unchecking this button.

The first thing we do is check the checkstate of the button. If it is checked, the user wants to start a copy operation on the selected files, otherwise they are cancelling. After this check we then prompt the user for the destination folder using the GetDestinationDir method. If the user actually specifies a target folder, then we go ahead and copy the files selected using the CopySong method, and give a progress update while we do so. You'll note that in the copy loop, we continually check if the user unchecked the button in case they want to cancel the operation.

CopySong: This method is used to copy songs from the iPod to the users machine. The real value of this method is that is converts the song from it's F0#\XXXX.mp# directory path\name storage structure on the iPod to an organized Artist\Album\Song (using title) format on the target machine. I wont describe too much in this method since much of it is self explainatory. Basically we create the directories needed and copy the song over with the new name.

And that's it! As you can see the UI is fairly small and straight forward. It could definitely use some more robust error handling, and the user could really mess things up if they wanted to, but this is just an example after all.

Final Thoughts

So that's it for the article. I hope you got an idea of what the ITunesDB file is all about, and how you can create objects that represent it's elements and retrieve song information. Though this is just an example built for fun, I hope it provided enough structured and readable code to help you design your own applications. Let me know if you have any questions and comments.

View iPod Nano songs without iTunes, C# Express, Part 4

2006-01-14T22:19:00.000-08:00

In this post we are going to create the ITunesDBLib class library.

I want to warn you first though, I'm not going to walk through all the steps to create the entire solution or the project (you can't expect me to write out everything!), instead I'll give you a screenshot of the entire solution with the ITunesDBLib selected in it, and we'll discuss the objects and code contained in the project. You are of course free to download the actual source code here and examine it in more detail.

Here is the screenshot of the complete solution in the project explorer window with the ITunesDBLib project and it's subfolders expanded...

You'll see that the ITunesDBLib project is currently selected. Within the project are a couple subfolders to help organize the classes. It may seem silly at first to create subfolders for only a small set of classes, but I find it good practice to always keep your projects organized. This kind of thinking pays off big when you start dealing enterprise applications where large numbers of classes come into play.

Here are the list of classes and a general description of each one...

ITunesDBManager: This is the 'engine' class of the assembly and the primary communication object. Consumers of the library should create an instance of this class to perform database operations. It's primary function is to provide the methods to open and retrieve database information from the iTunesDB file.

View ITunesDBManager Code (View)

You'll notice a Delegate is declared at the top. This is to allow consumers to handle any progress events coming from this class and any children below it. If you are unfamilar with delegates and events, I'd recommend you check them out here first, though it's not totally necessary to understand them to use this code.

The two main declarations to note are the byte array to hold the data from the iTunesDB file...
private byte[] itunesDB;

and the top level element in the iTunesDB file
private MHBD mhbd;

The consumer of the class will first call the LoadITunesDatabase method and pass in the path to the iTunesDB file. Within this method we use the framework File object's ReadAllBytes method to load the contents of the iTunesDB binary file into the ituneDB byte array. We can then use the array in memory to search for values. This is a more efficient approach than reopening the actual binary file each time we need to find a song.

Right after we load the byte array, we then pass it to the Load method of the MHBD object, which is the top level element in the iTunesDB file. NOTE: If you haven't looked at the object heirarchy yet of the iTunesDB file, now would be a good time, you can find it here. The MHBD object inherits the DBNodeBase class (discussed later) and overrides the Load method to populate itself with values from the byte array. Any children below it also override the Load method to populate themselves and their children, and so on until all objects are loaded.

GlobalUtility: This is a static class that provides assembly wide enumerations and functions. The key methods in here allow conversion from byte arrays to strings and number types. Here's the code...

View GlobalUtility Code (View)

The enums are used help define elements that can contain different types of information. For example, an MHSD element can contain either Track\Image, Playlist\AlbumList or PodList\FileList type information.

The main methods to note are the AsciiByteArrayToString\UnicodeByteArrayToString, and the ByteArrayToNumber methods. These guys do the work of converting the byte information into strings and numbers respectively.

DBNodeBase: This abstract class is the base class for all elements in the iTunesDB file. Generally all elements in an iTunesDB heirarchy will need the properties and methods contained in this class, therefore all elements should inherit from it.

View DBNodeBase code (View)

The important method to note is the Load method, which will be overridden by the inheriting class. The two parameters are the byte array which contains all the binary data, and the offset which is used to tell the object where to start getting data in the byte array. Since we don't know ahead of time where items lie exactly in the binary file, we have to figure out where the parent node stopped to know where the next node begins.

MHODBase: This abstract class is the base class for MHOD elements. MHOD elements are a very special structures in the iTunesDB file and can contain several flavors of data. This is the primary reason why it requires a base class.

View MHODBase Code (View)

MHBD: This is the top level element in the iTunesDB heirarchy. This element is pretty much analagous to the Root node in an xml file. Within it are all the child elements that make up the complete iTunesDB data.

View MHDB Code (View)

The most important thing to note in this class is the code in the overriden Load method. Within this method, you will see we are getting data directly out of the byte array, and storing it into the object's properties. Currently the length of each set of bytes to read are hardcoded in the object, though we could make these constants if we prefered or centralize them in another class (it's just a demo after all!).

MHSD: This element describes a set of data. The data can one of three types (TrackList\ImageList, PlayList\AlbumList, or PodList\FileList.

View MHSD Code (View)

The key area to look at in this class is the check for the type of data we are loading in the Load method. Right now we are only looking for a TrackList, but the capacity exists to look for PlayList and FileLists as well.

MHLT: This element describes a TrackList. Other than it denoting a tracklist, we really don't care too much about it other than it's children.

View MHLT Code (View)

MHIT: This element is the actual Track or Song. This is the most important element in our application since contains the lions share of information for a specific song, including the Artist, Album and Song Title. It also contains a MHODString child element that has the location of the actual song file.

View MHIT Code (View)

MHODString: This is a specific type of MHOD element that only contains a string value.

View MHODString Code (View)

The important item to note in this class is the check in the Load method to see if this type of MHODString is a Location type. If so, then we need to strip out illegal characters from the path to the song (not sure why apple puts in crazy characters in the location file, you're guess is as good as mine).

So that's it for the ITunesDBLib object heirarchy and code! Overall, it's pretty straight forward, but might be confusing if you haven't looked at the iTunesDB file structure. Keep in mind also that these are only the core objects required to load the song list. If we wanted to, we could easily extend this assembly to include the other elements (such as favorites and custom playlists), or even the Artwork data if we wanted. We could also include code to add songs to the byte array, and write everything back to the iTunesDB file to save changes. For this example though, we are just keeping it simple.

In the next post, we'll talk about the iPodBrowserExampleUI project, and take a look at it's code.

View iPod Nano songs without iTunes, C# Express, Part 3

2006-01-14T20:16:00.000-08:00

So now that we know what we are going to build, we need to determine what technologies we are going to use, and what our software design will be.

Technology

The technology we'll use is C# Express. I'm not going to bore you with all the reasons why I choose to use C# instead of VB.NET. I have a VB.NET background myself, but for the past few years I've focused mostly only C# (mostly due to recent contracts), and now I'm simply more comfortable with it. To be honest I think both have their good points - but I'll save the comparisons for a different post.

Software Design

I'm not going to show you class diagrams or sequence diagrams or any other kind of grams; I do enough of that on the job and it's really not necessary for something this small. For enterprise projects in the work environment you should definitely create at least a class diagram, but for this I'm just going to describe the components.

ITunesDBLib
This is the first component we need to create. It is a class library assembly and its primary function is to read data from the iTunesDB file. It represents the communication 'engine' for the iTunes database. Within it we will create the objects that represent the song elements in the iTunesDB file. We will look at the actual code for this component in the next post.

IPodBrowserExampleUI
This is the UI component. It is a windows forms exe that will use the ITunesDBLib class library to get data and display it. It will also have functions to play and extract songs to the computer.

Together these two components will be the entirety of our application.

In the next post, we'll create the ITunesDBLib class library, and you'll get to see some actual code.

View iPod Nano songs without iTunes, C# Express, Part 2

2006-01-14T19:20:00.000-08:00

In this post, I'll discuss the application goals, and describe the general idea of what we are creating.

Application Goals: What are we creating?

Basically what we want to create is a C# application that resides on the iPod Nano. When this application is run, it will bring up a list of all the songs on the iPod (both protected and non-protected). Once the list is populated, the user can select a song and play it using the default song player (NOTE: This is not a hack program. If the song is a protected iTunes mp4 file, it will not play unless the user has iTunes installed and is licensed to view the song).

Another function the user can perform is to the extract song(s) from the iPod to the current machine. The extracted songs will be placed in a readable Artist\Album\Song Name directory structure format.

Here is a screenshot of what we want to create...

In order to create this application, we will need to answer a couple questions:
1 - Where is the song list stored, and in what format?
2 - Where are the songs themselves stored?
3 - Where does that one missing sock go after washing my clothes?

Although we may never know the answer to 3, we can answer the first two questions with some degree of certainty.

1 - The song list is stored in the \iPod_Control\ITunes\iTunesDB file on the iPod. This is the good news. The bad news is that the data is stored in binary and in a rather funky structure. Luckily all the hard work to decipher what the bytes mean and how the file is structured has already been figured out by the folks at ipodlinux.org. Here is the page that describes the database file in all it's grisly glory: http://ipodlinux.org/ITunesDB. Make sure to bookmark this page (as I did) if you plan on extending this code or writing your own database file reader. It's an invaluable resource.

2 - The songs themselves are stored in the \iPod_Control\Music directory, in one of the F0# subfolders. If you open any of these subfolders, you will see that the songs have a bizarre naming structure "XXXX.mp#", where the XXXX is stuff like ABCD and DDCF. Why they did it this way is anyone's guess, though I suspect it's so nobody could do something as useful as copying songs from the iPod to a machine that doesn't have iTunes.

So that's the goal of the app - To open the binary db file, get the song list, and be able to associate that list to the actual song files. Once we have that associated list, we can play or copy the songs to a machine that doesn't have iTunes installed.

In the next post, I'll describe the two assemblies we are going to build: the database reader library and the UI.

View iPod Nano songs without iTunes, C# Express, Part 1

2006-01-14T18:31:00.000-08:00

In this post, I'll give some background information on what this project is about.

After receiving an iPod Nano from my wife, and downloading all the songs from my desktop to it, I was a bit perturbed to find out that even though a majority of my songs were in non-protected mp3 format, I could find no easy way to listen or port these songs to another computer that did not also have iTunes installed on it. I thought perhaps I could just look at the songs on the iPod itself and physically copy them, but alas, the song names are scrambled in some weirdo XXXX.mp3 format and not organized in any readable fashion. In researching this issue, I found that another person had also come across this issue and wrote a program in VB6 that can view and extract the songs on the iPod. This program is called SharePod and the source code is free.

Although SharePod works great, its written in VB6, and the code is a bit hard on developers. There are no comments, and little OO structure. I decided that a fun project would be to write a similar (albeit slightly trimmed) application in C#, that does basically the same thing. In doing so I would learn quite a bit about the iTunesDB file, which is the core iPod music database file. Yes, I know, there are likely others out there that have done the same thing, but doing it yourself is part of the fun isn't it?

In the next post, I'll discuss the application goals.