# Name

VixVM_CopyFileFromGuestToHost

# Description

    VixHandle
    VixVM_CopyFileFromGuestToHost(VixHandle vmHandle,
                                  const char* guestPathName,
                                  const char* hostPathName,
                                  int options,
                                  VixHandle propertyListHandle,
                                  VixEventProc *callbackProc,
                                  void *clientData);

Copies a file or directory from the guest operating system to the local system (where the Vix client is running).

# Parameters

vmHandle
  Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
guestPathName
  The path name of a file on a file system available to the guest.
hostPathName
  The path name of a file on a file system available to the Vix client.
options
  Must be 0.
propertyListHandle
  Must be VIX_INVALID_HANDLE.
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

- The virtual machine must be running while the file is copied from its guest operating system to the Vix client machine.
- Existing files of the same name are overwritten, and folder contents are merged.
- The copy operation requires VMware Tools to be installed and running in the guest operating system.
- You must call VixVM_LoginInGuest() before calling this procedure.
- The format of the file name depends on the guest or host operating system. For example, a path name for a Microsoft Windows guest or host requires backslash as a directory separator, whereas a Linux guest or host requires a forward slash. If the path name includes backslash characters, you need to precede each one with an escape character.
- Only absolute paths should be used for files in the guest; the resolution of relative paths is not specified.
- If any file fails to be copied, Vix aborts the operation, does not attempt to copy the remaining files, and returns an error.
- In order to copy a file from a mapped network drive in a Windows guest operating system, it is necessary to call VixVM_LoginInGuest() with the VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT flag set. Using the interactive session option incurs an overhead in file transfer speed.

# Side Effects

None.

# Requirements

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

# Example

This example copies a compiled object file from a virtual machine to be run on the host.

    VixError err = VIX_OK;
    VixHandle hostHandle = VIX_INVALID_HANDLE;
    VixHandle jobHandle = VIX_INVALID_HANDLE;
    VixHandle vmHandle = VIX_INVALID_HANDLE;

    jobHandle = VixHost_Connect(VIX_API_VERSION,
                                VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                                NULL, // hostName
                                0, // hostPort
                                NULL, // userName
                                NULL, // password
                                0, // options
                                VIX_INVALID_HANDLE, // propertyListHandle
                                NULL, // callbackProc
                                NULL); // clientData

    err = VixJob_Wait(jobHandle,
                      VIX_PROPERTY_JOB_RESULT_HANDLE,
                      &hostHandle,
                      VIX_PROPERTY_NONE);

    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }
    Vix_ReleaseHandle(jobHandle);
    jobHandle = VixVM_Open(hostHandle,
                           "c:\\Virtual Machines\\vm1\\win2000.vmx",
                           NULL, // callbackProc
                           NULL); // clientData
    err = VixJob_Wait(jobHandle,
                      VIX_PROPERTY_JOB_RESULT_HANDLE,
                      &vmHandle,
                      VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    // Power on the virtual machine before copying file.
    jobHandle = VixVM_PowerOn(vmHandle,
                              0, // powerOnOptions
                              VIX_INVALID_HANDLE, // propertyListHandle
                              NULL, // callbackProc
                              NULL); // clientData

    err = VixJob_Wait(jobHandle,VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    // Wait until guest is completely booted.
    jobHandle = VixVM_WaitForToolsInGuest(vmHandle,
                                          300, // timeoutInSeconds
                                          NULL, // callbackProc
                                          NULL); // clientData

    err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    // Authenticate for guest operations.
    jobHandle = VixVM_LoginInGuest(vmHandle,
                                   "vixuser", // userName
                                   "secret", // password
                                   0, // options
                                   NULL, // callbackProc
                                   NULL); // clientData

    err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    // Copy the file.
    jobHandle = VixVM_CopyFileFromGuestToHost(vmHandle,
                                              "c:\\guestDir\\helloworld.o", // src name
                                              "c:\\hostDir\\helloworld.o",  // dest name
                                              0, // options
                                              VIX_INVALID_HANDLE, // propertyListHandle
                                              NULL, // callbackProc
                                              NULL); // clientData
    err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);

    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    abort:
    Vix_ReleaseHandle(jobHandle);
    Vix_ReleaseHandle(vmHandle);
    VixHost_Disconnect(hostHandle);

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