# Name

VixVM_CaptureScreenImage

# Description

    VixHandle
    VixVM_CaptureScreenImage(VixHandle vmHandle,
                             int captureType,
                             VixHandle additionalProperties,
                             VixEventProc *callbackProc,
                             void *clientdata);

This function captures the screen of the guest operating system.

# Parameters

vmHandle
  The handle to the VM.
captureType
  the data format. Must be VIX_CAPTURESCREENFORMAT_PNG
additionalProperties
  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

This function captures the current screen image and returns it as a job result property of type 'blob'. When a blob is returned as a job property, it is returned as two values: first an 'int' containing the blob size in bytes, then a pointer to the blob.

The image size is also available as a separate job result property.

These properties are available from the job handle as a result of the function call:

- VIX_PROPERTY_JOB_RESULT_SCREEN_IMAGE_DATA: a blob property containing the bytes making up the image
- VIX_PROPERTY_JOB_RESULT_SCREEN_IMAGE_SIZE: an int containing the size of the image, in bytes

The caller is responsible for calling Vix_FreeBuffer() to free the screen image buffer when no longer needed.

For security reasons, this function requires a successful call to VixVM_LoginInGuest must be made.

# Side Effects

None.

# Requirements

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

# Example

    job = VixVM_CaptureScreenImage(vm,
                                   VIX_CAPTURESCREENFORMAT_PNG,
                                   VIX_INVALID_HANDLE,
                                   NULL,
                                   NULL);
    err = VixJob_Wait(job,
                      VIX_PROPERTY_JOB_RESULT_SCREEN_IMAGE_DATA,
                      &byte_count, &screen_bits,
                      VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       fprintf(stderr, "failed to capture screen in guest vm '%s'(%"FMT64"d %s)\n",
               vmpath,
               err,
               Vix_GetErrorText(err, NULL));
       goto abort;
    }
    Vix_ReleaseHandle(job);

    printf("got image back, %d bytes\n", byte_count);
    FILE *fp = fopen("screen.png", "wb+");
    if (fp) {
       fwrite(screen_bits, byte_count, 1, fp);
       fclose(fp);
    }
    // Free blob memory when done.
    Vix_FreeBuffer(screen_bits);

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