doc/html/gnome-vfs-finding-special-directories.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >Finding Special Directories</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
   8 "><LINK
   9 REL="HOME"
  10 TITLE="GnomeVFS - Filesystem Abstraction library"
  11 HREF="index.html"><LINK
  12 REL="UP"
  13 TITLE="Basic File Operations"
  14 HREF="file-operations.html"><LINK
  15 REL="PREVIOUS"
  16 TITLE="Directory Operations"
  17 HREF="gnome-vfs-directory.html"><LINK
  18 REL="NEXT"
  19 TITLE="Asynchronous File I/O"
  20 HREF="gnome-vfs-asynchronous-operations.html"></HEAD
  21 ><BODY
  22 CLASS="REFENTRY"
  23 BGCOLOR="#FFFFFF"
  24 TEXT="#000000"
  25 LINK="#0000FF"
  26 VLINK="#840084"
  27 ALINK="#0000FF"
  28 ><DIV
  29 CLASS="NAVHEADER"
  30 ><TABLE
  31 WIDTH="100%"
  32 BORDER="0"
  33 BGCOLOR="#000000"
  34 CELLPADDING="1"
  35 CELLSPACING="0"
  36 ><TR
  37 ><TH
  38 COLSPAN="4"
  39 ALIGN="center"
  40 ><FONT
  41 COLOR="#FFFFFF"
  42 SIZE="5"
  43 >GnomeVFS - Filesystem Abstraction library</FONT
  44 ></TH
  45 ></TR
  46 ><TR
  47 ><TD
  48 WIDTH="25%"
  49 BGCOLOR="#C00000"
  50 ALIGN="left"
  51 ><A
  52 HREF="gnome-vfs-directory.html"
  53 ><FONT
  54 COLOR="#FFFFFF"
  55 SIZE="3"
  56 ><B
  57 >&#60;&#60;&#60; Previous Page</B
  58 ></FONT
  59 ></A
  60 ></TD
  61 ><TD
  62 WIDTH="25%"
  63 BGCOLOR="#0000C0"
  64 ALIGN="center"
  65 ><FONT
  66 COLOR="#FFFFFF"
  67 SIZE="3"
  68 ><B
  69 ><A
  70 HREF="index.html"
  71 ><FONT
  72 COLOR="#FFFFFF"
  73 SIZE="3"
  74 ><B
  75 >Home</B
  76 ></FONT
  77 ></A
  78 ></B
  79 ></FONT
  80 ></TD
  81 ><TD
  82 WIDTH="25%"
  83 BGCOLOR="#00C000"
  84 ALIGN="center"
  85 ><FONT
  86 COLOR="#FFFFFF"
  87 SIZE="3"
  88 ><B
  89 ><A
  90 HREF="file-operations.html"
  91 ><FONT
  92 COLOR="#FFFFFF"
  93 SIZE="3"
  94 ><B
  95 >Up</B
  96 ></FONT
  97 ></A
  98 ></B
  99 ></FONT
 100 ></TD
 101 ><TD
 102 WIDTH="25%"
 103 BGCOLOR="#C00000"
 104 ALIGN="right"
 105 ><A
 106 HREF="gnome-vfs-asynchronous-operations.html"
 107 ><FONT
 108 COLOR="#FFFFFF"
 109 SIZE="3"
 110 ><B
 111 >Next Page &#62;&#62;&#62;</B
 112 ></FONT
 113 ></A
 114 ></TD
 115 ></TR
 116 ></TABLE
 117 ></DIV
 118 ><H1
 119 ><A
 120 NAME="GNOME-VFS-FINDING-SPECIAL-DIRECTORIES"
 121 >Finding Special Directories</A
 122 ></H1
 123 ><DIV
 124 CLASS="REFNAMEDIV"
 125 ><A
 126 NAME="AEN1501"
 127 ></A
 128 ><H2
 129 >Name</H2
 130 >Finding Special Directories&nbsp;--&nbsp;how to locate special directories such as the trash and desktop</DIV
 131 ><DIV
 132 CLASS="REFSYNOPSISDIV"
 133 ><A
 134 NAME="AEN1504"
 135 ></A
 136 ><H2
 137 >Synopsis</H2
 138 ><TABLE
 139 BORDER="0"
 140 BGCOLOR="#D6E8FF"
 141 WIDTH="100%"
 142 CELLPADDING="6"
 143 ><TR
 144 ><TD
 145 ><PRE
 146 CLASS="SYNOPSIS"
 147 >&#13;
 148
 149 <A
 150 HREF="gnome-vfs-types.html#GNOMEVFSRESULT"
 151 >GnomeVFSResult</A
 152 > <A
 153 HREF="gnome-vfs-finding-special-directories.html#GNOME-VFS-FIND-DIRECTORY"
 154 >gnome_vfs_find_directory</A
 155 >     (GnomeVFSURI *near_uri,
 156                                              <A
 157 HREF="gnome-vfs-types.html#GNOMEVFSFINDDIRECTORYKIND"
 158 >GnomeVFSFindDirectoryKind</A
 159 > kind,
 160                                              GnomeVFSURI **result,
 161                                              <A
 162 HREF=../glib/glib-basic-types.html#GBOOLEAN
 163 >gboolean</A> create_if_needed,
 164                                              <A
 165 HREF=../glib/glib-basic-types.html#GBOOLEAN
 166 >gboolean</A> find_if_needed,
 167                                              <A
 168 HREF=../glib/glib-basic-types.html#GUINT
 169 >guint</A> permissions);</PRE
 170 ></TD
 171 ></TR
 172 ></TABLE
 173 ></DIV
 174 ><DIV
 175 CLASS="REFSECT1"
 176 ><A
 177 NAME="AEN1515"
 178 ></A
 179 ><H2
 180 >Description</H2
 181 ><P
 182 ></P
 183 ></DIV
 184 ><DIV
 185 CLASS="REFSECT1"
 186 ><A
 187 NAME="AEN1518"
 188 ></A
 189 ><H2
 190 >Details</H2
 191 ><DIV
 192 CLASS="REFSECT2"
 193 ><A
 194 NAME="AEN1520"
 195 ></A
 196 ><H3
 197 ><A
 198 NAME="GNOME-VFS-FIND-DIRECTORY"
 199 ></A
 200 >gnome_vfs_find_directory ()</H3
 201 ><TABLE
 202 BORDER="0"
 203 BGCOLOR="#D6E8FF"
 204 WIDTH="100%"
 205 CELLPADDING="6"
 206 ><TR
 207 ><TD
 208 ><PRE
 209 CLASS="PROGRAMLISTING"
 210 ><A
 211 HREF="gnome-vfs-types.html#GNOMEVFSRESULT"
 212 >GnomeVFSResult</A
 213 > gnome_vfs_find_directory     (GnomeVFSURI *near_uri,
 214                                              <A
 215 HREF="gnome-vfs-types.html#GNOMEVFSFINDDIRECTORYKIND"
 216 >GnomeVFSFindDirectoryKind</A
 217 > kind,
 218                                              GnomeVFSURI **result,
 219                                              <A
 220 HREF=../glib/glib-basic-types.html#GBOOLEAN
 221 >gboolean</A> create_if_needed,
 222                                              <A
 223 HREF=../glib/glib-basic-types.html#GBOOLEAN
 224 >gboolean</A> find_if_needed,
 225                                              <A
 226 HREF=../glib/glib-basic-types.html#GUINT
 227 >guint</A> permissions);</PRE
 228 ></TD
 229 ></TR
 230 ></TABLE
 231 ><P
 232 >Used to return well known directories such as Trash, Desktop, etc. from different
 233 file systems.</P
 234 ><P
 235 >There is quite a complicated logic behind finding/creating a Trash directory
 236 and you need to be aware of some implications:
 237 Finding the Trash the first time when using the file method may be pretty
 238 expensive. A cache file is used to store the location of that Trash file
 239 for next time.
 240 If <TT
 241 CLASS="PARAMETER"
 242 ><I
 243 >ceate_if_needed</I
 244 ></TT
 245 > is specified without <TT
 246 CLASS="PARAMETER"
 247 ><I
 248 >find_if_needed</I
 249 ></TT
 250 >, you may end up
 251 creating a Trash file when there already is one. Your app should start out
 252 by doing a gnome_vfs_find_directory with the <TT
 253 CLASS="PARAMETER"
 254 ><I
 255 >find_if_needed</I
 256 ></TT
 257 > to avoid this
 258 and then use the <TT
 259 CLASS="PARAMETER"
 260 ><I
 261 >create_if_needed</I
 262 ></TT
 263 > flag to create Trash lazily when it is
 264 needed for throwing away an item on a given disk.</P
 265 ><P
 266 ></P
 267 ><DIV
 268 CLASS="INFORMALTABLE"
 269 ><A
 270 NAME="AEN1538"
 271 ></A
 272 ><P
 273 ></P
 274 ><TABLE
 275 BORDER="0"
 276 WIDTH="100%"
 277 BGCOLOR="#FFD0D0"
 278 CELLSPACING="0"
 279 CELLPADDING="4"
 280 CLASS="CALSTABLE"
 281 ><TBODY
 282 ><TR
 283 ><TD
 284 WIDTH="20%"
 285 ALIGN="RIGHT"
 286 VALIGN="TOP"
 287 ><TT
 288 CLASS="PARAMETER"
 289 ><I
 290 >near_uri</I
 291 ></TT
 292 >&nbsp;:</TD
 293 ><TD
 294 WIDTH="80%"
 295 ALIGN="LEFT"
 296 VALIGN="TOP"
 297 > find a well known directory on the same volume as <TT
 298 CLASS="PARAMETER"
 299 ><I
 300 >near_uri</I
 301 ></TT
 302 ></TD
 303 ></TR
 304 ><TR
 305 ><TD
 306 WIDTH="20%"
 307 ALIGN="RIGHT"
 308 VALIGN="TOP"
 309 ><TT
 310 CLASS="PARAMETER"
 311 ><I
 312 >kind</I
 313 ></TT
 314 >&nbsp;:</TD
 315 ><TD
 316 WIDTH="80%"
 317 ALIGN="LEFT"
 318 VALIGN="TOP"
 319 > kind of well known directory</TD
 320 ></TR
 321 ><TR
 322 ><TD
 323 WIDTH="20%"
 324 ALIGN="RIGHT"
 325 VALIGN="TOP"
 326 ><TT
 327 CLASS="PARAMETER"
 328 ><I
 329 >result</I
 330 ></TT
 331 >&nbsp;:</TD
 332 ><TD
 333 WIDTH="80%"
 334 ALIGN="LEFT"
 335 VALIGN="TOP"
 336 > newly created URI of the directory we found</TD
 337 ></TR
 338 ><TR
 339 ><TD
 340 WIDTH="20%"
 341 ALIGN="RIGHT"
 342 VALIGN="TOP"
 343 ><TT
 344 CLASS="PARAMETER"
 345 ><I
 346 >create_if_needed</I
 347 ></TT
 348 >&nbsp;:</TD
 349 ><TD
 350 WIDTH="80%"
 351 ALIGN="LEFT"
 352 VALIGN="TOP"
 353 > If directory we are looking for does not exist, try to create it</TD
 354 ></TR
 355 ><TR
 356 ><TD
 357 WIDTH="20%"
 358 ALIGN="RIGHT"
 359 VALIGN="TOP"
 360 ><TT
 361 CLASS="PARAMETER"
 362 ><I
 363 >find_if_needed</I
 364 ></TT
 365 >&nbsp;:</TD
 366 ><TD
 367 WIDTH="80%"
 368 ALIGN="LEFT"
 369 VALIGN="TOP"
 370 > If we don't know where trash is yet, look for it.</TD
 371 ></TR
 372 ><TR
 373 ><TD
 374 WIDTH="20%"
 375 ALIGN="RIGHT"
 376 VALIGN="TOP"
 377 ><TT
 378 CLASS="PARAMETER"
 379 ><I
 380 >permissions</I
 381 ></TT
 382 >&nbsp;:</TD
 383 ><TD
 384 WIDTH="80%"
 385 ALIGN="LEFT"
 386 VALIGN="TOP"
 387 > If creating, use these permissions</TD
 388 ></TR
 389 ><TR
 390 ><TD
 391 WIDTH="20%"
 392 ALIGN="RIGHT"
 393 VALIGN="TOP"
 394 ><I
 395 CLASS="EMPHASIS"
 396 >Returns</I
 397 > :</TD
 398 ><TD
 399 WIDTH="80%"
 400 ALIGN="LEFT"
 401 VALIGN="TOP"
 402 > An integer representing the result of the operation</TD
 403 ></TR
 404 ></TBODY
 405 ></TABLE
 406 ><P
 407 ></P
 408 ></DIV
 409 ></DIV
 410 ></DIV
 411 ><DIV
 412 CLASS="NAVFOOTER"
 413 ><BR
 414 CLEAR="all"><BR><TABLE
 415 WIDTH="100%"
 416 BORDER="0"
 417 BGCOLOR="#000000"
 418 CELLPADDING="1"
 419 CELLSPACING="0"
 420 ><TR
 421 ><TD
 422 WIDTH="25%"
 423 BGCOLOR="#C00000"
 424 ALIGN="left"
 425 ><A
 426 HREF="gnome-vfs-directory.html"
 427 ><FONT
 428 COLOR="#FFFFFF"
 429 SIZE="3"
 430 ><B
 431 >&#60;&#60;&#60; Previous Page</B
 432 ></FONT
 433 ></A
 434 ></TD
 435 ><TD
 436 WIDTH="25%"
 437 BGCOLOR="#0000C0"
 438 ALIGN="center"
 439 ><FONT
 440 COLOR="#FFFFFF"
 441 SIZE="3"
 442 ><B
 443 ><A
 444 HREF="index.html"
 445 ><FONT
 446 COLOR="#FFFFFF"
 447 SIZE="3"
 448 ><B
 449 >Home</B
 450 ></FONT
 451 ></A
 452 ></B
 453 ></FONT
 454 ></TD
 455 ><TD
 456 WIDTH="25%"
 457 BGCOLOR="#00C000"
 458 ALIGN="center"
 459 ><FONT
 460 COLOR="#FFFFFF"
 461 SIZE="3"
 462 ><B
 463 ><A
 464 HREF="file-operations.html"
 465 ><FONT
 466 COLOR="#FFFFFF"
 467 SIZE="3"
 468 ><B
 469 >Up</B
 470 ></FONT
 471 ></A
 472 ></B
 473 ></FONT
 474 ></TD
 475 ><TD
 476 WIDTH="25%"
 477 BGCOLOR="#C00000"
 478 ALIGN="right"
 479 ><A
 480 HREF="gnome-vfs-asynchronous-operations.html"
 481 ><FONT
 482 COLOR="#FFFFFF"
 483 SIZE="3"
 484 ><B
 485 >Next Page &#62;&#62;&#62;</B
 486 ></FONT
 487 ></A
 488 ></TD
 489 ></TR
 490 ><TR
 491 ><TD
 492 COLSPAN="2"
 493 ALIGN="left"
 494 ><FONT
 495 COLOR="#FFFFFF"
 496 SIZE="3"
 497 ><B
 498 >Directory Operations</B
 499 ></FONT
 500 ></TD
 501 ><TD
 502 COLSPAN="2"
 503 ALIGN="right"
 504 ><FONT
 505 COLOR="#FFFFFF"
 506 SIZE="3"
 507 ><B
 508 >Asynchronous File I/O</B
 509 ></FONT
 510 ></TD
 511 ></TR
 512 ></TABLE
 513 ></DIV
 514 ></BODY
 515 ></HTML
 516 >