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);