doc/html/gnome-vfs-gnome-vfs-find-directory.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >Locating Standard Directories</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
   8 "><LINK
   9 REL="HOME"
  10 TITLE="GnomeVFS - Filesystem Abstraction library"
  11 HREF="index.html"><LINK
  12 REL="UP"
  13 TITLE="Directories"
  14 HREF="directory-operations.html"><LINK
  15 REL="PREVIOUS"
  16 TITLE="Directory Operations"
  17 HREF="gnome-vfs-gnome-vfs-directory.html"><LINK
  18 REL="NEXT"
  19 TITLE="Advanced Operations"
  20 HREF="advanced-operations.html"><META
  21 NAME="GENERATOR"
  22 CONTENT="GTK-Doc V0.10 (SGML mode)"><STYLE
  23 TYPE="text/css"
  24 >.synopsis, .classsynopsis {
  25     background: #eeeeee;
  26     border: solid 1px #aaaaaa;
  27     padding: 0.5em;
  28 }
  29 .programlisting {
  30     background: #eeeeff;
  31     border: solid 1px #aaaaff;
  32     padding: 0.5em;
  33 }
  34 .variablelist {
  35     padding: 4px;
  36     margin-left: 3em;
  37 }
  38 .navigation {
  39     background: #ffeeee;
  40     border: solid 1px #ffaaaa;
  41     margin-top: 0.5em;
  42     margin-bottom: 0.5em;
  43 }
  44 .navigation a {
  45     color: #770000;
  46 }
  47 .navigation a:visited {
  48     color: #550000;
  49 }
  50 .navigation .title {
  51     font-size: 200%;
  52 }</STYLE
  53 ></HEAD
  54 ><BODY
  55 CLASS="REFENTRY"
  56 BGCOLOR="#FFFFFF"
  57 TEXT="#000000"
  58 LINK="#0000FF"
  59 VLINK="#840084"
  60 ALINK="#0000FF"
  61 ><TABLE
  62 WIDTH="100%"
  63 CLASS="navigation"
  64 SUMMARY="Navigation header"
  65 CELLPADDING="2"
  66 CELLSPACING="2"
  67 ><TR
  68 VALIGN="middle"
  69 ><TD
  70 ><A
  71 ACCESSKEY="p"
  72 HREF="gnome-vfs-gnome-vfs-directory.html"
  73 ><IMG
  74 SRC="left.png"
  75 WIDTH="24"
  76 HEIGHT="24"
  77 BORDER="0"
  78 ALT="Prev"></A
  79 ></TD
  80 ><TD
  81 ><A
  82 ACCESSKEY="u"
  83 HREF="directory-operations.html"
  84 ><IMG
  85 SRC="up.png"
  86 WIDTH="24"
  87 HEIGHT="24"
  88 BORDER="0"
  89 ALT="Up"></A
  90 ></TD
  91 ><TD
  92 ><A
  93 ACCESSKEY="h"
  94 HREF="index.html"
  95 ><IMG
  96 SRC="home.png"
  97 WIDTH="24"
  98 HEIGHT="24"
  99 BORDER="0"
 100 ALT="Home"></A
 101 ></TD
 102 ><TH
 103 WIDTH="100%"
 104 align="center"
 105 >GnomeVFS - Filesystem Abstraction library</TH
 106 ><TD
 107 ><A
 108 ACCESSKEY="n"
 109 HREF="advanced-operations.html"
 110 ><IMG
 111 SRC="right.png"
 112 WIDTH="24"
 113 HEIGHT="24"
 114 BORDER="0"
 115 ALT="Next"></A
 116 ></TD
 117 ></TR
 118 ></TABLE
 119 ><H1
 120 ><A
 121 NAME="GNOME-VFS-GNOME-VFS-FIND-DIRECTORY"
 122 ></A
 123 >Locating Standard Directories</H1
 124 ><DIV
 125 CLASS="REFNAMEDIV"
 126 ><A
 127 NAME="AEN3097"
 128 ></A
 129 ><H2
 130 >Name</H2
 131 >Locating Standard Directories&nbsp;--&nbsp;utilities for locating standard directories such as the desktop and trash</DIV
 132 ><DIV
 133 CLASS="REFSYNOPSISDIV"
 134 ><A
 135 NAME="AEN3100"
 136 ></A
 137 ><H2
 138 >Synopsis</H2
 139 ><PRE
 140 CLASS="SYNOPSIS"
 141 >&#13;
 142
 143 enum        <A
 144 HREF="gnome-vfs-gnome-vfs-find-directory.html#GNOMEVFSFINDDIRECTORYKIND"
 145 >GnomeVFSFindDirectoryKind</A
 146 >;
 147 <A
 148 HREF="gnome-vfs-gnome-vfs-result.html#GNOMEVFSRESULT"
 149 >GnomeVFSResult</A
 150 > <A
 151 HREF="gnome-vfs-gnome-vfs-find-directory.html#GNOME-VFS-FIND-DIRECTORY"
 152 >gnome_vfs_find_directory</A
 153 >     (GnomeVFSURI *near_uri,
 154                                              <A
 155 HREF="gnome-vfs-gnome-vfs-find-directory.html#GNOMEVFSFINDDIRECTORYKIND"
 156 >GnomeVFSFindDirectoryKind</A
 157 > kind,
 158                                              GnomeVFSURI **result,
 159                                              gboolean create_if_needed,
 160                                              gboolean find_if_needed,
 161                                              guint permissions);</PRE
 162 ></DIV
 163 ><DIV
 164 CLASS="REFSECT1"
 165 ><A
 166 NAME="AEN3112"
 167 ></A
 168 ><H2
 169 >Description</H2
 170 ><P
 171 ></P
 172 ></DIV
 173 ><DIV
 174 CLASS="REFSECT1"
 175 ><A
 176 NAME="AEN3115"
 177 ></A
 178 ><H2
 179 >Details</H2
 180 ><DIV
 181 CLASS="REFSECT2"
 182 ><A
 183 NAME="AEN3117"
 184 ></A
 185 ><H3
 186 ><A
 187 NAME="GNOMEVFSFINDDIRECTORYKIND"
 188 ></A
 189 >enum GnomeVFSFindDirectoryKind</H3
 190 ><PRE
 191 CLASS="PROGRAMLISTING"
 192 >typedef enum {
 193         GNOME_VFS_DIRECTORY_KIND_DESKTOP = 1000,
 194         GNOME_VFS_DIRECTORY_KIND_TRASH = 1001
 195 } GnomeVFSFindDirectoryKind;</PRE
 196 ><P
 197 ></P
 198 ></DIV
 199 ><HR><DIV
 200 CLASS="REFSECT2"
 201 ><A
 202 NAME="AEN3122"
 203 ></A
 204 ><H3
 205 ><A
 206 NAME="GNOME-VFS-FIND-DIRECTORY"
 207 ></A
 208 >gnome_vfs_find_directory ()</H3
 209 ><PRE
 210 CLASS="PROGRAMLISTING"
 211 ><A
 212 HREF="gnome-vfs-gnome-vfs-result.html#GNOMEVFSRESULT"
 213 >GnomeVFSResult</A
 214 > gnome_vfs_find_directory     (GnomeVFSURI *near_uri,
 215                                              <A
 216 HREF="gnome-vfs-gnome-vfs-find-directory.html#GNOMEVFSFINDDIRECTORYKIND"
 217 >GnomeVFSFindDirectoryKind</A
 218 > kind,
 219                                              GnomeVFSURI **result,
 220                                              gboolean create_if_needed,
 221                                              gboolean find_if_needed,
 222                                              guint permissions);</PRE
 223 ><P
 224 >Used to return well known directories such as Trash, Desktop, etc. from different
 225 file systems.</P
 226 ><P
 227 >There is quite a complicated logic behind finding/creating a Trash directory
 228 and you need to be aware of some implications:
 229 Finding the Trash the first time when using the file method may be pretty
 230 expensive. A cache file is used to store the location of that Trash file
 231 for next time.
 232 If <TT
 233 CLASS="PARAMETER"
 234 ><I
 235 >ceate_if_needed</I
 236 ></TT
 237 > is specified without <TT
 238 CLASS="PARAMETER"
 239 ><I
 240 >find_if_needed</I
 241 ></TT
 242 >, you may end up
 243 creating a Trash file when there already is one. Your app should start out
 244 by doing a gnome_vfs_find_directory with the <TT
 245 CLASS="PARAMETER"
 246 ><I
 247 >find_if_needed</I
 248 ></TT
 249 > to avoid this
 250 and then use the <TT
 251 CLASS="PARAMETER"
 252 ><I
 253 >create_if_needed</I
 254 ></TT
 255 > flag to create Trash lazily when it is
 256 needed for throwing away an item on a given disk.</P
 257 ><P
 258 ></P
 259 ><P
 260 ></P
 261 ><TABLE
 262 CLASS="variablelist"
 263 BORDER="0"
 264 CELLSPACING="0"
 265 CELLPADDING="4"
 266 ><TBODY
 267 ><TR
 268 ><TD
 269 ALIGN="LEFT"
 270 VALIGN="TOP"
 271 ><A
 272 NAME="AEN3141"><SPAN
 273 STYLE="white-space: nowrap"
 274 ><TT
 275 CLASS="PARAMETER"
 276 ><I
 277 >near_uri</I
 278 ></TT
 279 >&nbsp;:</SPAN
 280 ></TD
 281 ><TD
 282 ALIGN="LEFT"
 283 VALIGN="TOP"
 284 ><P
 285 > find a well known directory on the same volume as <TT
 286 CLASS="PARAMETER"
 287 ><I
 288 >near_uri</I
 289 ></TT
 290 ></P
 291 ></TD
 292 ></TR
 293 ><TR
 294 ><TD
 295 ALIGN="LEFT"
 296 VALIGN="TOP"
 297 ><A
 298 NAME="AEN3147"><SPAN
 299 STYLE="white-space: nowrap"
 300 ><TT
 301 CLASS="PARAMETER"
 302 ><I
 303 >kind</I
 304 ></TT
 305 >&nbsp;:</SPAN
 306 ></TD
 307 ><TD
 308 ALIGN="LEFT"
 309 VALIGN="TOP"
 310 ><P
 311 > kind of well known directory</P
 312 ></TD
 313 ></TR
 314 ><TR
 315 ><TD
 316 ALIGN="LEFT"
 317 VALIGN="TOP"
 318 ><A
 319 NAME="AEN3152"><SPAN
 320 STYLE="white-space: nowrap"
 321 ><TT
 322 CLASS="PARAMETER"
 323 ><I
 324 >result</I
 325 ></TT
 326 >&nbsp;:</SPAN
 327 ></TD
 328 ><TD
 329 ALIGN="LEFT"
 330 VALIGN="TOP"
 331 ><P
 332 > newly created URI of the directory we found</P
 333 ></TD
 334 ></TR
 335 ><TR
 336 ><TD
 337 ALIGN="LEFT"
 338 VALIGN="TOP"
 339 ><A
 340 NAME="AEN3157"><SPAN
 341 STYLE="white-space: nowrap"
 342 ><TT
 343 CLASS="PARAMETER"
 344 ><I
 345 >create_if_needed</I
 346 ></TT
 347 >&nbsp;:</SPAN
 348 ></TD
 349 ><TD
 350 ALIGN="LEFT"
 351 VALIGN="TOP"
 352 ><P
 353 > If directory we are looking for does not exist, try to create it</P
 354 ></TD
 355 ></TR
 356 ><TR
 357 ><TD
 358 ALIGN="LEFT"
 359 VALIGN="TOP"
 360 ><A
 361 NAME="AEN3162"><SPAN
 362 STYLE="white-space: nowrap"
 363 ><TT
 364 CLASS="PARAMETER"
 365 ><I
 366 >find_if_needed</I
 367 ></TT
 368 >&nbsp;:</SPAN
 369 ></TD
 370 ><TD
 371 ALIGN="LEFT"
 372 VALIGN="TOP"
 373 ><P
 374 > If we don't know where trash is yet, look for it.</P
 375 ></TD
 376 ></TR
 377 ><TR
 378 ><TD
 379 ALIGN="LEFT"
 380 VALIGN="TOP"
 381 ><A
 382 NAME="AEN3167"><SPAN
 383 STYLE="white-space: nowrap"
 384 ><TT
 385 CLASS="PARAMETER"
 386 ><I
 387 >permissions</I
 388 ></TT
 389 >&nbsp;:</SPAN
 390 ></TD
 391 ><TD
 392 ALIGN="LEFT"
 393 VALIGN="TOP"
 394 ><P
 395 > If creating, use these permissions</P
 396 ></TD
 397 ></TR
 398 ><TR
 399 ><TD
 400 ALIGN="LEFT"
 401 VALIGN="TOP"
 402 ><A
 403 NAME="AEN3172"><SPAN
 404 STYLE="white-space: nowrap"
 405 ><SPAN
 406 CLASS="emphasis"
 407 ><I
 408 CLASS="EMPHASIS"
 409 >Returns</I
 410 ></SPAN
 411 > :</SPAN
 412 ></TD
 413 ><TD
 414 ALIGN="LEFT"
 415 VALIGN="TOP"
 416 ><P
 417 > An integer representing the result of the operation</P
 418 ></TD
 419 ></TR
 420 ></TBODY
 421 ></TABLE
 422 ></DIV
 423 ></DIV
 424 ><TABLE
 425 CLASS="navigation"
 426 WIDTH="100%"
 427 SUMMARY="Navigation footer"
 428 CELLPADDING="2"
 429 CELLSPACING="2"
 430 ><TR
 431 VALIGN="middle"
 432 ><TD
 433 ALIGN="left"
 434 ><A
 435 ACCESSKEY="p"
 436 HREF="gnome-vfs-gnome-vfs-directory.html"
 437 ><B
 438 >&lt;&lt;&lt;&nbsp;Directory Operations</B
 439 ></A
 440 ></TD
 441 ><TD
 442 ALIGN="right"
 443 ><A
 444 ACCESSKEY="n"
 445 HREF="advanced-operations.html"
 446 ><B
 447 >Advanced Operations&nbsp;&gt;&gt;&gt;</B
 448 ></A
 449 ></TD
 450 ></TR
 451 ></TABLE
 452 ></BODY
 453 ></HTML
 454 >