1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
<!-- ##### SECTION Title ##### -->
iPod database reading/writing
<!-- ##### SECTION Short_Description ##### -->
Functions to read, write, and create an iPod database
<!-- ##### SECTION Long_Description ##### -->
<para>
These functions are for reading, writing, creating, and deleting an iPod
database and getting the total number of tracks and playlists.
</para>
<para>
Overview of using an iPod database:
</para>
<para>
itdb_parse(): read the iTunesDB and ArtworkDB
</para>
<para>
itdb_write(): write the iTunesDB and ArtworkDB
</para>
<para>
itdb_parse() will return a #Itdb_iTunesDB structure with GLists
containing all tracks the playlists in the database. Each track is
represented by an #Itdb_Track. Each playlist is represented by an
#Itdb_Playlist. See the <link linkend="libgpod-Tracks">Tracks</link>
and <link linkend="libgpod-Playlists">Playlists</link> sections for
details on tracks and playlists, respectively.
</para>
<para>
Each #Itdb_Playlist has a GList called @members which contains all of
the tracks in the playlist. Tracks referenced in a playlist must also
be present in the @tracks GList of the #Itdb_iTunesDB.
</para>
<para>
The iPod must contain one master playlist (MPL) containing all tracks
accessible on the iPod through the Music->Tracks/Albums/Artists/etc.
menu. In addition to the MPL there can be a number of normal
playlists accessible through the Music->Playlists menu on the iPod.
Tracks that are a member of one of these normal playlists must also be
a member of the MPL.
</para>
<para>
The Podcasts playlist is just another playlist with some internal
flags set differently. Tracks in the Podcasts playlist are not
normally members of the MPL (so on the iPod they will only show up
under the Podcasts menu). All tracks referenced must be in the
@tracks GList of the #Itdb_iTunesDB, however.
</para>
<para>
Each track may have a thumbnail associated with it. You can retrieve a
#GdkPixmap of the thumbnail using itdb_artwork_get_pixbuf(). A
thumbnail can be added with itdb_track_set_thumbnails(). A thumbnail
can be removed with itdb_track_remove_thumbnails(). Please see the
<link linkend="libgpod-Artwork">Artwork</link> section for more
details on artwork related functions and structures.
</para>
<note>
<para>
Be aware that iTunes additionally stores the artwork as tags
in the original music file. That's also from where the data is
read when artwork is displayed in iTunes, and there can be more
than one piece of artwork. libgpod does not store the artwork as
tags in the original music file. As a consequence, if iTunes
attempts to access the artwork, it will find none, and remove
libgpod's artwork. Luckily, iTunes will only attempt to access
the artwork if you select a track in iTunes. To work around
this, gtkpod keeps a list of the original filename of all
artwork and silently adds the thumbnails if they were 'lost'.
Your application might want to do something similar, or you can
supply patches for (optionally!) adding tags to the original music
files.
</para>
</note>
<para>
The #Itdb_iTunesDB, #Itdb_Playlist and #Itdb_Track structures each
have @userdata and @usertype fields that can be used by the
application to store additional application-specific data. If
@userdata is a pointer to an external structure, you can supply a
#ItdbUserDataDuplicateFunc and a #ItdbUserDataDestroyFunc so that this
data can be duplicated or freed automatically with a call to the
library _duplicate()/_free() functions.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT Itdb_iTunesDB ##### -->
<para>
</para>
@tracks:
@playlists:
@filename:
@device:
@version:
@id:
@reserved_int1:
@reserved_int2:
@reserved1:
@reserved2:
@usertype:
@userdata:
@userdata_duplicate:
@userdata_destroy:
<!-- ##### ENUM ItdbFileError ##### -->
<para>
</para>
@ITDB_FILE_ERROR_SEEK:
@ITDB_FILE_ERROR_CORRUPT:
@ITDB_FILE_ERROR_NOTFOUND:
@ITDB_FILE_ERROR_RENAME:
@ITDB_FILE_ERROR_ITDB_CORRUPT:
<!-- ##### FUNCTION itdb_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION itdb_free ##### -->
<para>
</para>
@itdb:
<!-- ##### FUNCTION itdb_parse ##### -->
<para>
</para>
@mp:
@error:
@Returns:
<!-- ##### FUNCTION itdb_write ##### -->
<para>
</para>
@itdb:
@error:
@Returns:
<!-- ##### FUNCTION itdb_set_mountpoint ##### -->
<para>
</para>
@itdb:
@mp:
<!-- ##### FUNCTION itdb_get_mountpoint ##### -->
<para>
</para>
@itdb:
@Returns:
<!-- ##### FUNCTION itdb_tracks_number ##### -->
<para>
</para>
@itdb:
@Returns:
<!-- ##### FUNCTION itdb_tracks_number_nontransferred ##### -->
<para>
</para>
@itdb:
@Returns:
<!-- ##### FUNCTION itdb_playlists_number ##### -->
<para>
</para>
@itdb:
@Returns:
<!-- ##### USER_FUNCTION ItdbUserDataDestroyFunc ##### -->
<para>
</para>
@userdata:
<!-- ##### USER_FUNCTION ItdbUserDataDuplicateFunc ##### -->
<para>
</para>
@userdata:
@Returns:
|
