diff options
Diffstat (limited to 'include/libimobiledevice/screenshotr.h')
| -rw-r--r-- | include/libimobiledevice/screenshotr.h | 94 |
1 files changed, 77 insertions, 17 deletions
diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h index b3669ee..db3c969 100644 --- a/include/libimobiledevice/screenshotr.h +++ b/include/libimobiledevice/screenshotr.h @@ -4,7 +4,8 @@ * @note Requires a mounted developer image. * \internal * - * Copyright (c) 2010 Nikias Bassen All Rights Reserved. + * Copyright (c) 2010-2019 Nikias Bassen, All Rights Reserved. + * Copyright (c) 2010-2014 Martin Szulecki, All Rights Reserved. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -29,27 +30,86 @@ extern "C" { #endif #include <libimobiledevice/libimobiledevice.h> +#include <libimobiledevice/lockdown.h> -/** @name Error Codes */ -/*@{*/ -#define SCREENSHOTR_E_SUCCESS 0 -#define SCREENSHOTR_E_INVALID_ARG -1 -#define SCREENSHOTR_E_PLIST_ERROR -2 -#define SCREENSHOTR_E_MUX_ERROR -3 -#define SCREENSHOTR_E_BAD_VERSION -4 +/** Service identifier passed to lockdownd_start_service() to start the screenshotr service */ +#define SCREENSHOTR_SERVICE_NAME "com.apple.mobile.screenshotr" -#define SCREENSHOTR_E_UNKNOWN_ERROR -256 -/*@}*/ +/** Error Codes */ +typedef enum { + SCREENSHOTR_E_SUCCESS = 0, + SCREENSHOTR_E_INVALID_ARG = -1, + SCREENSHOTR_E_PLIST_ERROR = -2, + SCREENSHOTR_E_MUX_ERROR = -3, + SCREENSHOTR_E_SSL_ERROR = -4, + SCREENSHOTR_E_RECEIVE_TIMEOUT = -5, + SCREENSHOTR_E_BAD_VERSION = -6, + SCREENSHOTR_E_UNKNOWN_ERROR = -256 +} screenshotr_error_t; -/** Represents an error code. */ -typedef int16_t screenshotr_error_t; - -typedef struct screenshotr_client_private screenshotr_client_private; +typedef struct screenshotr_client_private screenshotr_client_private; /**< \private */ typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */ -screenshotr_error_t screenshotr_client_new(idevice_t device, uint16_t port, screenshotr_client_t * client); -screenshotr_error_t screenshotr_client_free(screenshotr_client_t client); -screenshotr_error_t screenshotr_take_screenshot(screenshotr_client_t client, char **imgdata, uint64_t *imgsize); + +/** + * Connects to the screenshotr service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * screenshotr_client_t upon successful return. + * + * @note This service is only available if a developer disk image has been + * mounted. + * + * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID ARG if one + * or more parameters are invalid, or SCREENSHOTR_E_CONN_FAILED if the + * connection to the device could not be established. + */ +LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_client_new(idevice_t device, lockdownd_service_descriptor_t service, screenshotr_client_t * client); + +/** + * Starts a new screenshotr service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * screenshotr_client_t upon successful return. Must be freed using + * screenshotr_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return SCREENSHOTR_E_SUCCESS on success, or an SCREENSHOTR_E_* error + * code otherwise. + */ +LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_client_start_service(idevice_t device, screenshotr_client_t* client, const char* label); + +/** + * Disconnects a screenshotr client from the device and frees up the + * screenshotr client data. + * + * @param client The screenshotr client to disconnect and free. + * + * @return SCREENSHOTR_E_SUCCESS on success, or SCREENSHOTR_E_INVALID_ARG + * if client is NULL. + */ +LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_client_free(screenshotr_client_t client); + + +/** + * Get a screen shot from the connected device. + * + * @param client The connection screenshotr service client. + * @param imgdata Pointer that will point to a newly allocated buffer + * containing TIFF image data upon successful return. It is up to the + * caller to free the memory. + * @param imgsize Pointer to a uint64_t that will be set to the size of the + * buffer imgdata points to upon successful return. + * + * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID_ARG if + * one or more parameters are invalid, or another error code if an + * error occurred. + */ +LIBIMOBILEDEVICE_API screenshotr_error_t screenshotr_take_screenshot(screenshotr_client_t client, char **imgdata, uint64_t *imgsize); #ifdef __cplusplus } |