# Name

VixVM_ListDirectoryInGuest

# Description

    VixHandle
    VixVM_ListDirectoryInGuest(VixHandle vmHandle,
                               const char *pathname,
                               int options,
                               VixEventProc *callbackProc,
                               void *clientData);

This function lists a directory in the guest operating system.

# Parameters

vmHandle
  Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
pathname
  The path name of a directory to be listed.
options
  Must be 0.
callbackProc
  A callback function that will be invoked when the operation is complete.
clientData
  A parameter that will be passed to the callbackProc function.

# Return Value

VixHandle. A job handle that describes the state of this asynchronous operation.

# Remarks

- You must call VixVM_LoginInGuest() before calling this function.
- VixJob_GetNumProperties() should be used to determine the number of results.
- VixJob_GetNthProperties() can be used to get each result.
- When the job is signaled, the following list of properties will be available on the returned job handle:
  - VIX_PROPERTY_JOB_RESULT_ITEM_NAME: the file name
  - VIX_PROPERTY_JOB_RESULT_FILE_SIZE: file size as a 64-bit integer. The file size is zero for child directories.
  - VIX_PROPERTY_JOB_RESULT_FILE_FLAGS: file attribute flags The flags are:
    - VIX_FILE_ATTRIBUTES_DIRECTORY - Set if the pathname identifies a directory.
    - VIX_FILE_ATTRIBUTES_SYMLINK- Set if the pathname identifies a symbolic link file.
  - VIX_PROPERTY_JOB_RESULT_FILE_MOD_TIME: The modification time of the file or directory as a 64-bit integer specifying seconds since the epoch.
- Only absolute paths should be used for files in the guest; the resolution of relative paths is not specified.

# Side Effects

None.

# Requirements

vix.h, since VMware Workstation 6.0
Minimum Supported Guest OS: Microsoft Windows NT Series, Linux

# Example

       job = VixVM_ListDirectoryInGuest(vm, guestdir, 0, NULL, NULL);
       err = VixJob_Wait(job, VIX_PROPERTY_NONE);
       if (VIX_OK != err) {
          fprintf(stderr, "failed to list dir '%s' in vm '%s'(%"FMT64"d %s)\n",
                  guestdir, vmpath, err, Vix_GetErrorText(err, NULL));
          goto abort;
       }

       num = VixJob_GetNumProperties(job, VIX_PROPERTY_JOB_RESULT_ITEM_NAME);
       for (i = 0; i < num; i++) {
          char *fname;

          err = VixJob_GetNthProperties(job,
                                        i,
                                        VIX_PROPERTY_JOB_RESULT_ITEM_NAME,
                                        &fname,
                                        VIX_PROPERTY_NONE);

          printf("file #%d '%s'\n", i, fname);

          Vix_FreeBuffer(fname);
       }

       Vix_ReleaseHandle(job);

Copyright (C) 2007-2018 VMware, Inc. All rights reserved.