| OLD | NEW |
| (Empty) |
| 1 // Copyright (c) 2009 The Chromium Authors. All rights reserved. | |
| 2 // Use of this source code is governed by a BSD-style license that can be | |
| 3 // found in the LICENSE file. | |
| 4 // | |
| 5 // This header specifies the Chrome Plugin API. It is based heavily on NPAPI. | |
| 6 // The key difference is that Chrome plugins can be loaded for the lifetime | |
| 7 // of the browser, and are not tied to a specific web page. | |
| 8 // | |
| 9 // NOTE: This API is not final and may change or go away at any point. | |
| 10 // | |
| 11 // All strings in the API are UTF8-encoded unless otherwise noted. | |
| 12 | |
| 13 #ifndef CHROME_COMMON_CHROME_PLUGIN_API_H__ | |
| 14 #define CHROME_COMMON_CHROME_PLUGIN_API_H__ | |
| 15 #pragma once | |
| 16 | |
| 17 #include "base/basictypes.h" | |
| 18 | |
| 19 #ifndef STDCALL | |
| 20 #ifdef WIN32 | |
| 21 #define STDCALL __stdcall | |
| 22 #else | |
| 23 #define STDCALL | |
| 24 #endif // WIN32 | |
| 25 #endif // STDCALL | |
| 26 | |
| 27 #ifdef __cplusplus | |
| 28 extern "C" { | |
| 29 #endif | |
| 30 | |
| 31 // The current version of the API, used by the 'version' field of CPPluginFuncs | |
| 32 // and CPBrowserFuncs. | |
| 33 #define CP_MAJOR_VERSION 0 | |
| 34 #define CP_MINOR_VERSION 11 | |
| 35 #define CP_VERSION ((CP_MAJOR_VERSION << 8) | (CP_MINOR_VERSION)) | |
| 36 | |
| 37 #define CP_GET_MAJOR_VERSION(version) ((version & 0xff00) >> 8) | |
| 38 #define CP_GET_MINOR_VERSION(version) (version & 0x00ff) | |
| 39 | |
| 40 typedef unsigned char CPBool; | |
| 41 | |
| 42 // Chrome plugins can be loaded into different process types. | |
| 43 typedef enum { | |
| 44 CP_PROCESS_BROWSER = 0, | |
| 45 CP_PROCESS_PLUGIN, | |
| 46 CP_PROCESS_RENDERER, | |
| 47 } CPProcessType; | |
| 48 | |
| 49 // Return codes. Error values are negative. | |
| 50 typedef enum { | |
| 51 // No error | |
| 52 CPERR_SUCCESS = 0, | |
| 53 | |
| 54 // (network) An asynchronous IO operation is not complete | |
| 55 CPERR_IO_PENDING = -1, | |
| 56 | |
| 57 // Generic failure | |
| 58 CPERR_FAILURE = -2, | |
| 59 | |
| 60 // The API versions used by plugin and host are incompatible | |
| 61 CPERR_INVALID_VERSION = -3, | |
| 62 | |
| 63 // The operation was cancelled | |
| 64 CPERR_CANCELLED = -4, | |
| 65 | |
| 66 // An invalid parameter was passed | |
| 67 CPERR_INVALID_PARAMETER = -5, | |
| 68 } CPError; | |
| 69 | |
| 70 // Types of response info metadata to query using CPP_GetResponseInfo. | |
| 71 typedef enum { | |
| 72 // HTTP status code. | |
| 73 CPRESPONSEINFO_HTTP_STATUS = 0, | |
| 74 | |
| 75 // Raw headers from the server, including the status line. Headers should | |
| 76 // be delimited by "\0", and end with "\0\0" (a blank line). | |
| 77 CPRESPONSEINFO_HTTP_RAW_HEADERS = 1, | |
| 78 } CPResponseInfoType; | |
| 79 | |
| 80 // An identifier for the plugin used by the browser. | |
| 81 typedef struct _CPID_t { | |
| 82 int unused; | |
| 83 } CPID_t; | |
| 84 typedef struct _CPID_t* CPID; | |
| 85 | |
| 86 // An identifier that encapsulates the browsing context needed by various APIs. | |
| 87 // This includes information about what tab a request was made from, and what | |
| 88 // profile is active. Note that this ID is global to all processes, so it can | |
| 89 // be passed from one process to another. The value 0 is reserved for an | |
| 90 // undefined context. | |
| 91 typedef uint32 CPBrowsingContext; | |
| 92 | |
| 93 // Types of context info to query using CPB_GetBrowsingContextInfo. | |
| 94 typedef enum { | |
| 95 // The data directory for the profile associated with this context as a | |
| 96 // pointer to a null-terminated string. The plugin can save persistent data | |
| 97 // to this directory. The returned pointer should be freed using CPB_Free. | |
| 98 CPBROWSINGCONTEXT_DATA_DIR_PTR = 0, | |
| 99 | |
| 100 // The locale language code used for the browser UI. The returned pointer | |
| 101 // should be freed using CPB_Free. | |
| 102 CPBROWSINGCONTEXT_UI_LOCALE_PTR = 1, | |
| 103 } CPBrowsingContextInfoType; | |
| 104 | |
| 105 // A network request object. | |
| 106 typedef struct _CPRequest { | |
| 107 void* pdata; // plugin private data | |
| 108 const char* url; // the URL being requested | |
| 109 const char* method; // the request method as an uppercase string (ex: "GET") | |
| 110 CPBrowsingContext context; // context in which this request was made | |
| 111 } CPRequest; | |
| 112 | |
| 113 typedef enum { | |
| 114 CPREQUESTLOAD_NORMAL = 0, | |
| 115 | |
| 116 // This is "normal reload", meaning an if-none-match/if-modified-since query | |
| 117 CPREQUESTLOAD_VALIDATE_CACHE = 1 << 0, | |
| 118 | |
| 119 // This is "shift-reload", meaning a "pragma: no-cache" end-to-end fetch | |
| 120 CPREQUESTLOAD_BYPASS_CACHE = 1 << 1, | |
| 121 | |
| 122 // This is a back/forward style navigation where the cached content should | |
| 123 // be preferred over any protocol specific cache validation. | |
| 124 CPREQUESTLOAD_PREFERRING_CACHE = 1 << 2, | |
| 125 | |
| 126 // This is a navigation that will fail if it cannot serve the requested | |
| 127 // resource from the cache (or some equivalent local store). | |
| 128 CPREQUESTLOAD_ONLY_FROM_CACHE = 1 << 3, | |
| 129 | |
| 130 // This is a navigation that will not use the cache at all. It does not | |
| 131 // impact the HTTP request headers. | |
| 132 CPREQUESTLOAD_DISABLE_CACHE = 1 << 4, | |
| 133 | |
| 134 // This navigation should not be intercepted by plugins. | |
| 135 CPREQUESTLOAD_DISABLE_INTERCEPT = 1 << 5, | |
| 136 | |
| 137 // This request should be loaded synchronously. What this means is that | |
| 138 // CPR_StartRequest and CPR_Read will never return CPERR_IO_PENDING - they | |
| 139 // will block until a response is available, and return success or failure. | |
| 140 CPREQUESTLOAD_SYNCHRONOUS = 1 << 20, | |
| 141 } CPRequestLoadFlags; | |
| 142 | |
| 143 // | |
| 144 // Functions provided by plugin to host. | |
| 145 // | |
| 146 | |
| 147 // Called when the browser is unloading the plugin. | |
| 148 typedef CPError (STDCALL *CPP_ShutdownFunc)(void); | |
| 149 | |
| 150 // Returns true if the plugin is interested in handling this request. | |
| 151 typedef CPBool (STDCALL *CPP_ShouldInterceptRequestFunc)(CPRequest* request); | |
| 152 | |
| 153 // Called when an HTML dialog was closed. json_retval is the JSON string | |
| 154 // containing the return value sent back by the dialog (using Chrome's | |
| 155 // JavaScript DOM bindings). | |
| 156 typedef void (STDCALL *CPP_HtmlDialogClosedFunc)( | |
| 157 void* plugin_context, const char* json_retval); | |
| 158 | |
| 159 // Asks the plugin to handle the given command. 'command_data' is command- | |
| 160 // specific data used for some builtin commands: see gears_api.h for | |
| 161 // possible types. It is only valid for the duration of this call. | |
| 162 typedef CPError (STDCALL *CPP_HandleCommandFunc)( | |
| 163 CPBrowsingContext context, int command, void* command_data); | |
| 164 | |
| 165 // | |
| 166 // Functions provided by host to plugin. | |
| 167 // | |
| 168 | |
| 169 // Asks the host to handle the given command. 'command_data' is | |
| 170 // command-specific data used for some builtin commands: see gears_api.h for | |
| 171 // possible types. It is only valid for the duration of this call. | |
| 172 typedef CPError (STDCALL *CPB_HandleCommandFunc)( | |
| 173 CPID id, CPBrowsingContext context, int command, void* command_data); | |
| 174 | |
| 175 // Asks the browser to enable/disable request interception for this plugin for | |
| 176 // the given schemes. 'schemes' is an array of strings containing the scheme | |
| 177 // names the plugin wishes to handle; case is ignored. If 'schemes' is NULL or | |
| 178 // empty, request interception is disabled for this plugin. Multiple calls to | |
| 179 // this function will add to the existing set of enabled schemes. The browser | |
| 180 // should call the plugin's CPP_ShouldInterceptRequestFunc for any network | |
| 181 // requests it makes that match a given scheme. The browser may choose not to | |
| 182 // allow the plugin to intercept certain protocols. | |
| 183 typedef void (STDCALL *CPB_EnableRequestInterceptFunc)( | |
| 184 CPID id, const char** schemes, uint32 num_schemes); | |
| 185 | |
| 186 // Asks the browser to create a request object for the given method/url. | |
| 187 // Returns CPERR_SUCCESS and puts the new object into the 'request' field on | |
| 188 // success, or an error code on failure. The plugin must call CPR_EndRequest | |
| 189 // to clean up the request object when it is done with it. | |
| 190 typedef CPError (STDCALL *CPB_CreateRequestFunc)( | |
| 191 CPID id, CPBrowsingContext context, const char* method, const char* url, | |
| 192 CPRequest** request); | |
| 193 | |
| 194 // Queries the browser's cookie store for cookies set for the given URL. | |
| 195 // Sets 'cookies' to an allocated string containing the cookies as | |
| 196 // semicolon-delimited "name=value" pairs on success, NULL on failure. | |
| 197 // The memory should be freed using CPB_Free when done. | |
| 198 typedef CPError (STDCALL *CPB_GetCookiesFunc)( | |
| 199 CPID id, CPBrowsingContext context, const char* url, char** cookies); | |
| 200 | |
| 201 // Allocates memory for the given size using the browser's allocator. Call | |
| 202 // CPB_Free when done. | |
| 203 typedef void* (STDCALL *CPB_AllocFunc)(uint32 size); | |
| 204 | |
| 205 // Frees a pointer allocated by CPB_Alloc. | |
| 206 typedef void (STDCALL *CPB_FreeFunc)(void* memory); | |
| 207 | |
| 208 | |
| 209 // Sets a flag that influences when the plugin process created to host | |
| 210 // the plugin is shutdown. Generally, the plugin process is terminated | |
| 211 // when no more plugin instances exist, this is the default behavior. | |
| 212 // If keep_alive is non-zero, the process will not be terminated when | |
| 213 // the instance count goes to zero. Note: a non-zero keep_alive value | |
| 214 // does not prevent the plugin process from being terminated upon | |
| 215 // overall browser shutdown. | |
| 216 typedef void (STDCALL *CPB_SetKeepProcessAliveFunc)(CPID id, | |
| 217 CPBool keep_alive); | |
| 218 | |
| 219 // Asks the browser to show an HTML dialog to the user. The dialog contents | |
| 220 // should be loaded from the given URL. The 'json_arguments' is a JSON string | |
| 221 // that the dialog can fetch using Chrome's JavaScript DOM bindings. This call | |
| 222 // will block until the dialog is closed. On success, 'json_retval' will | |
| 223 // contain the JSON string sent back by the dialog (using Chrome's JavaScript | |
| 224 // DOM bindings), and CPERR_SUCCESS is returned. 'json_retval' should be freed | |
| 225 // using CPB_Free when done. | |
| 226 typedef CPError (STDCALL *CPB_ShowHtmlDialogModalFunc)( | |
| 227 CPID id, CPBrowsingContext context, const char* url, int width, int height, | |
| 228 const char* json_arguments, char** json_retval); | |
| 229 | |
| 230 // Similar to CPB_ShowHtmlDialogModalFunc, but does not block. When the dialog | |
| 231 // is closed, CPP_HtmlDialogClosed is called with the JSON return value and the | |
| 232 // given 'plugin_context', which may be used by the plugin to associate other | |
| 233 // data with the dialog. | |
| 234 typedef CPError (STDCALL *CPB_ShowHtmlDialogFunc)( | |
| 235 CPID id, CPBrowsingContext context, const char* url, int width, int height, | |
| 236 const char* json_arguments, void* plugin_context); | |
| 237 | |
| 238 // Get the browsing context associated with the given NPAPI instance. | |
| 239 typedef CPBrowsingContext (STDCALL *CPB_GetBrowsingContextFromNPPFunc)( | |
| 240 struct _NPP* npp); | |
| 241 | |
| 242 // Queries for some meta data associated with the given browsing context. See | |
| 243 // CPBrowsingContextInfoType for possible queries. If buf_size is too small to | |
| 244 // contain the entire data, the return value will indicate the size required. | |
| 245 // Otherwise, the return value is a CPError or CPERR_SUCCESS. | |
| 246 typedef int (STDCALL *CPB_GetBrowsingContextInfoFunc)( | |
| 247 CPID id, CPBrowsingContext context, CPBrowsingContextInfoType type, | |
| 248 void* buf, uint32 buf_size); | |
| 249 | |
| 250 // Given an URL string, returns the string of command-line arguments that should | |
| 251 // be passed to start the browser at the given URL. 'arguments' should be freed | |
| 252 // using CPB_Free when done. | |
| 253 typedef CPError (STDCALL *CPB_GetCommandLineArgumentsFunc)( | |
| 254 CPID id, CPBrowsingContext context, const char* url, char** arguments); | |
| 255 | |
| 256 // Asks the browser to let the plugin handle the given UI command. When the | |
| 257 // command is invoked, the browser will call CPP_HandleCommand. 'command' | |
| 258 // should be an integer identifier. Currently only builtin commands are | |
| 259 // supported, but in the future we may want to let plugins add custom menu | |
| 260 // commands with their own descriptions. | |
| 261 typedef CPError (STDCALL *CPB_AddUICommandFunc)(CPID id, int command); | |
| 262 | |
| 263 // | |
| 264 // Functions related to making network requests. | |
| 265 // Both the host and plugin will implement their own versions of these. | |
| 266 // | |
| 267 | |
| 268 // Starts the request. Returns CPERR_SUCCESS if the request could be started | |
| 269 // immediately, at which point the response info is available to be read. | |
| 270 // Returns CPERR_IO_PENDING if an asynchronous operation was started, and the | |
| 271 // caller should wait for CPRR_StartCompleted to be called before reading the | |
| 272 // response info. Returns an error code on failure. | |
| 273 typedef CPError (STDCALL *CPR_StartRequestFunc)(CPRequest* request); | |
| 274 | |
| 275 // Stops or cancels the request. The caller should not access the request | |
| 276 // object after this call. If an asynchronous IO operation is pending, the | |
| 277 // operation is aborted and the caller will not receive a callback for it. | |
| 278 typedef void (STDCALL *CPR_EndRequestFunc)(CPRequest* request, CPError reason); | |
| 279 | |
| 280 // Sets the additional request headers to append to the standard headers that | |
| 281 // would normally be made with this request. Headers should be \r\n-delimited, | |
| 282 // with no terminating \r\n. Extra headers are not checked against the standard | |
| 283 // headers for duplicates. Must be called before CPRR_StartCompletedFunc. | |
| 284 // Plugins should avoid setting the following headers: User-Agent, | |
| 285 // Content-Length. | |
| 286 typedef void (STDCALL *CPR_SetExtraRequestHeadersFunc)(CPRequest* request, | |
| 287 const char* headers); | |
| 288 | |
| 289 // Sets the load flags for this request. 'flags' is a bitwise-OR of | |
| 290 // CPRequestLoadFlags. Must be called before CPRR_StartCompletedFunc. | |
| 291 typedef void (STDCALL *CPR_SetRequestLoadFlagsFunc)(CPRequest* request, | |
| 292 uint32 flags); | |
| 293 | |
| 294 // Appends binary data to the request body of a POST or PUT request. The caller | |
| 295 // should set the "Content-Type" header to the appropriate mime type using | |
| 296 // CPR_SetExtraRequestHeadersFunc. This can be called multiple times to append | |
| 297 // a sequence of data segments to upload. Must be called before | |
| 298 // CPR_StartRequestFunc. | |
| 299 typedef void (STDCALL *CPR_AppendDataToUploadFunc)( | |
| 300 CPRequest* request, const char* bytes, int bytes_len); | |
| 301 | |
| 302 // Appends the contents of a file to the request body of a POST or PUT request. | |
| 303 // 'offset' and 'length' can be used to append a subset of the file. Pass zero | |
| 304 // for 'length' and 'offset' to upload the entire file. 'offset' | |
| 305 // indicates where the data to upload begins in the file. 'length' indicates | |
| 306 // how much of the file to upload. A 'length' of zero is interpretted as to | |
| 307 // end-of-file. If 'length' and 'offset' indicate a range beyond end of file, | |
| 308 // the amount sent is clipped at eof. | |
| 309 // See CPR_AppendDataToUploadFunc for additional usage information. | |
| 310 // (added in v0.4) | |
| 311 typedef CPError (STDCALL *CPR_AppendFileToUploadFunc)( | |
| 312 CPRequest* request, const char* filepath, uint64 offset, uint64 length); | |
| 313 | |
| 314 // Queries for some response meta data. See CPResponseInfoType for possible | |
| 315 // queries. If buf_size is too small to contain the entire data, the return | |
| 316 // value will indicate the size required. Otherwise, the return value is a | |
| 317 // CPError or CPERR_SUCCESS. | |
| 318 typedef int (STDCALL *CPR_GetResponseInfoFunc)( | |
| 319 CPRequest* request, CPResponseInfoType type, | |
| 320 void* buf, uint32 buf_size); | |
| 321 | |
| 322 // Attempts to read a request's response data. The number of bytes read is | |
| 323 // returned; 0 indicates an EOF. CPERR_IO_PENDING is returned if an | |
| 324 // asynchronous operation was started, and CPRR_ReadCompletedFunc will be called | |
| 325 // when it completes; 'buf' must be available until the operation completes. | |
| 326 // Returns an error code on failure. | |
| 327 typedef int (STDCALL *CPR_ReadFunc)( | |
| 328 CPRequest* request, void* buf, uint32 buf_size); | |
| 329 | |
| 330 // | |
| 331 // Functions related to serving network requests. | |
| 332 // Both the host and plugin will implement their own versions of these. | |
| 333 // | |
| 334 | |
| 335 // Called upon a server-initiated redirect. The request will still hold the | |
| 336 // original URL, and 'new_url' will be the redirect destination. | |
| 337 typedef void (STDCALL *CPRR_ReceivedRedirectFunc)(CPRequest* request, | |
| 338 const char* new_url); | |
| 339 | |
| 340 // Called when an asynchronous CPR_StartRequest call has completed, once all | |
| 341 // redirects are followed. On success, 'result' holds CPERR_SUCCESS and the | |
| 342 // response info is available to be read via CPR_GetResponseInfo. On error, | |
| 343 // 'result' holds the error code. | |
| 344 typedef void (STDCALL *CPRR_StartCompletedFunc)(CPRequest* request, | |
| 345 CPError result); | |
| 346 | |
| 347 // Called when an asynchronous CPR_Read call has completed. On success, | |
| 348 // 'bytes_read' will hold the number of bytes read into the buffer that was | |
| 349 // passed to CPR_Read; 0 indicates an EOF, and the request object will be | |
| 350 // destroyed after the call completes. On failure, 'bytes_read' holds the error | |
| 351 // code. | |
| 352 typedef void (STDCALL *CPRR_ReadCompletedFunc)(CPRequest* request, | |
| 353 int bytes_read); | |
| 354 | |
| 355 // Called as upload progress is being made for async POST requests. | |
| 356 // (added in v0.5) | |
| 357 typedef void (STDCALL *CPRR_UploadProgressFunc)(CPRequest* request, | |
| 358 uint64 position, | |
| 359 uint64 size); | |
| 360 | |
| 361 // | |
| 362 // Functions to support the sending and receipt of messages between processes. | |
| 363 // | |
| 364 | |
| 365 // Returns true if the plugin process is running | |
| 366 typedef CPBool (STDCALL *CPB_IsPluginProcessRunningFunc)(CPID id); | |
| 367 | |
| 368 // Returns the type of the current process. | |
| 369 typedef CPProcessType (STDCALL *CPB_GetProcessTypeFunc)(CPID id); | |
| 370 | |
| 371 // Asks the browser to send raw data to the other process hosting an instance of | |
| 372 // this plugin. If needed, the plugin process will be started prior to sending | |
| 373 // the message. | |
| 374 typedef CPError (STDCALL *CPB_SendMessageFunc)(CPID id, | |
| 375 const void *data, | |
| 376 uint32 data_len); | |
| 377 | |
| 378 // Asks the browser to send raw data to the other process hosting an instance of | |
| 379 // this plugin. This function only works from the plugin or renderer process. | |
| 380 // This function blocks until the message is processed. The memory should be | |
| 381 // freed using CPB_Free when done. | |
| 382 typedef CPError (STDCALL *CPB_SendSyncMessageFunc)(CPID id, | |
| 383 const void *data, | |
| 384 uint32 data_len, | |
| 385 void **retval, | |
| 386 uint32 *retval_len); | |
| 387 | |
| 388 // This function asynchronously calls the provided function on the plugin | |
| 389 // thread. user_data is passed as the argument to the function. | |
| 390 typedef CPError (STDCALL *CPB_PluginThreadAsyncCallFunc)(CPID id, | |
| 391 void (*func)(void *), | |
| 392 void *user_data); | |
| 393 | |
| 394 // This function creates an open file dialog. The process is granted access | |
| 395 // to any files that are selected. |multiple_files| determines if more than | |
| 396 // one file can be selected. | |
| 397 typedef CPError (STDCALL *CPB_OpenFileDialogFunc)(CPID id, | |
| 398 CPBrowsingContext context, | |
| 399 bool multiple_files, | |
| 400 const char *title, | |
| 401 const char *filter, | |
| 402 void *user_data); | |
| 403 | |
| 404 // Informs the plugin of raw data having been sent from another process. | |
| 405 typedef void (STDCALL *CPP_OnMessageFunc)(void *data, uint32 data_len); | |
| 406 | |
| 407 // Informs the plugin of raw data having been sent from another process. | |
| 408 typedef void (STDCALL *CPP_OnSyncMessageFunc)(void *data, uint32 data_len, | |
| 409 void **retval, | |
| 410 uint32 *retval_len); | |
| 411 | |
| 412 // Informs the plugin that the file dialog has completed, and contains the | |
| 413 // results. | |
| 414 typedef void (STDCALL *CPP_OnFileDialogResultFunc)(void *data, | |
| 415 const char **files, | |
| 416 uint32 files_len); | |
| 417 | |
| 418 // Asks the browser to verify that NPObject* 'event' is the current drag event | |
| 419 // the browser is dispatching, and extract drag data from the event if so. On | |
| 420 // success, returns the drag 'identity' (an up-counter that the browser chrome | |
| 421 // increases each time a user drag enters a renderer tab), the drag 'event_id' | |
| 422 // and the 'drag_type' being a utf8 encoded string with values "Files", "Text" | |
| 423 // or "URL". If 'add_data' is true, also return the 'drag_data', again a utf8 | |
| 424 // encoded string with the data for the drag type. For drag type "Files", the | |
| 425 // data is a backspace delimited list of file paths. | |
| 426 // | |
| 427 // The call fails with a CPError if 'event' is an invalid drag event, and sets | |
| 428 // the 'identity' and 'event_id' to 0. Note: on success, non-NULL 'drag_type' | |
| 429 // and 'drag_data' should be freed with CPB_Free() when done. | |
| 430 typedef CPError (STDCALL *CPB_GetDragDataFunc)( | |
| 431 CPID id, CPBrowsingContext context, struct NPObject* event, bool add_data, | |
| 432 int32* identity, int32* event_id, char** drag_type, char** drag_data); | |
| 433 | |
| 434 // Asks the browser to verify that NPObject* 'event' is the current drag event | |
| 435 // the browser is dispatching and show the requested drop 'effect' if so. The | |
| 436 // browser displays drop effects during dragenter and dragover events, to give | |
| 437 // user visible feedback (with a drag cursor, typically) to indicate whether a | |
| 438 // subsequent drop event will succeed or not. The implementation supports the | |
| 439 // so-called "copy" and "none" effects. When 'effect' is non-zero, the "copy" | |
| 440 // effect is shown. Otherwise, the "none" effect is shown, which prevents the | |
| 441 // subsequent drop event from succeeding. Returns CPError on failure, meaning | |
| 442 // the 'event' is an invalid drag event. | |
| 443 // | |
| 444 // Note: 'effect' is int to allow for new effects in future. For example, the | |
| 445 // HTML5-defined drop effects "move" and "link". | |
| 446 typedef CPError (STDCALL *CPB_SetDropEffectFunc)( | |
| 447 CPID id, CPBrowsingContext context, struct NPObject* event, int effect); | |
| 448 | |
| 449 // For drag type "Files", the drag data returned by CPB_GetDragDataFunc() is a | |
| 450 // backspace delimited list of file paths. Use this routine to pass that data | |
| 451 // to the browser process to verify that the renderer has permission to access | |
| 452 // the files. Returns CPERR_SUCCESS if access is allowed. | |
| 453 typedef CPError (STDCALL *CPB_AllowFileDropFunc)( | |
| 454 CPID id, CPBrowsingContext context, const char* file_drag_data); | |
| 455 | |
| 456 // Function table for issuing requests using via the other side's network stack. | |
| 457 // For the plugin, this functions deal with issuing requests through the | |
| 458 // browser. For the browser, these functions deal with allowing the plugin to | |
| 459 // intercept requests. | |
| 460 typedef struct _CPRequestFuncs { | |
| 461 uint16 size; | |
| 462 CPR_SetExtraRequestHeadersFunc set_extra_request_headers; | |
| 463 CPR_SetRequestLoadFlagsFunc set_request_load_flags; | |
| 464 CPR_AppendDataToUploadFunc append_data_to_upload; | |
| 465 CPR_StartRequestFunc start_request; | |
| 466 CPR_EndRequestFunc end_request; | |
| 467 CPR_GetResponseInfoFunc get_response_info; | |
| 468 CPR_ReadFunc read; | |
| 469 CPR_AppendFileToUploadFunc append_file_to_upload; | |
| 470 } CPRequestFuncs; | |
| 471 | |
| 472 // Function table for handling requests issued by the other side. For the | |
| 473 // plugin, these deal with serving requests that the plugin has intercepted. For | |
| 474 // the browser, these deal with serving requests that the plugin has issued | |
| 475 // through us. | |
| 476 typedef struct _CPResponseFuncs { | |
| 477 uint16 size; | |
| 478 CPRR_ReceivedRedirectFunc received_redirect; | |
| 479 CPRR_StartCompletedFunc start_completed; | |
| 480 CPRR_ReadCompletedFunc read_completed; | |
| 481 CPRR_UploadProgressFunc upload_progress; | |
| 482 } CPResponseFuncs; | |
| 483 | |
| 484 // Function table of CPP functions (functions provided by plugin to host). This | |
| 485 // structure is filled in by the plugin in the CP_Initialize call, except for | |
| 486 // the 'size' field, which is set by the browser. The version fields should be | |
| 487 // set to those that the plugin was compiled using. | |
| 488 typedef struct _CPPluginFuncs { | |
| 489 uint16 size; | |
| 490 uint16 version; | |
| 491 CPRequestFuncs* request_funcs; | |
| 492 CPResponseFuncs* response_funcs; | |
| 493 CPP_ShutdownFunc shutdown; | |
| 494 CPP_ShouldInterceptRequestFunc should_intercept_request; | |
| 495 CPP_OnMessageFunc on_message; | |
| 496 CPP_HtmlDialogClosedFunc html_dialog_closed; | |
| 497 CPP_HandleCommandFunc handle_command; | |
| 498 CPP_OnSyncMessageFunc on_sync_message; | |
| 499 CPP_OnFileDialogResultFunc on_file_dialog_result; | |
| 500 } CPPluginFuncs; | |
| 501 | |
| 502 // Function table CPB functions (functions provided by host to plugin). | |
| 503 // This structure is filled in by the browser and provided to the plugin. The | |
| 504 // plugin will likely want to save a copy of this structure to make calls | |
| 505 // back to the browser. | |
| 506 typedef struct _CPBrowserFuncs { | |
| 507 uint16 size; | |
| 508 uint16 version; | |
| 509 CPRequestFuncs* request_funcs; | |
| 510 CPResponseFuncs* response_funcs; | |
| 511 CPB_EnableRequestInterceptFunc enable_request_intercept; | |
| 512 CPB_CreateRequestFunc create_request; | |
| 513 CPB_GetCookiesFunc get_cookies; | |
| 514 CPB_AllocFunc alloc; | |
| 515 CPB_FreeFunc free; | |
| 516 CPB_SetKeepProcessAliveFunc set_keep_process_alive; | |
| 517 CPB_ShowHtmlDialogModalFunc show_html_dialog_modal; | |
| 518 CPB_ShowHtmlDialogFunc show_html_dialog; | |
| 519 CPB_IsPluginProcessRunningFunc is_plugin_process_running; | |
| 520 CPB_GetProcessTypeFunc get_process_type; | |
| 521 CPB_SendMessageFunc send_message; | |
| 522 CPB_GetBrowsingContextFromNPPFunc get_browsing_context_from_npp; | |
| 523 CPB_GetBrowsingContextInfoFunc get_browsing_context_info; | |
| 524 CPB_GetCommandLineArgumentsFunc get_command_line_arguments; | |
| 525 CPB_AddUICommandFunc add_ui_command; | |
| 526 CPB_HandleCommandFunc handle_command; | |
| 527 CPB_SendSyncMessageFunc send_sync_message; | |
| 528 CPB_PluginThreadAsyncCallFunc plugin_thread_async_call; | |
| 529 CPB_OpenFileDialogFunc open_file_dialog; | |
| 530 CPB_GetDragDataFunc get_drag_data; | |
| 531 CPB_SetDropEffectFunc set_drop_effect; | |
| 532 CPB_AllowFileDropFunc allow_file_drop; | |
| 533 } CPBrowserFuncs; | |
| 534 | |
| 535 | |
| 536 // | |
| 537 // DLL exports | |
| 538 // | |
| 539 | |
| 540 // This export is optional. | |
| 541 // Prior to calling CP_Initialize, the browser may negotiate with the plugin | |
| 542 // regarding which version of the CPAPI to utilize. 'min_version' is the | |
| 543 // lowest version of the interface supported by the browser, 'max_version' is | |
| 544 // the highest supported version. The plugin can specify which version within | |
| 545 // the range should be used. This version will be reflected in the version field | |
| 546 // of the CPBrowserFuncs struct passed to CP_Initialize. If this function | |
| 547 // returns an error code, CP_Initialize will not be called. If function is not | |
| 548 // exported by the chrome plugin module, CP_Initiailize will be called with | |
| 549 // a version of the host's choosing. | |
| 550 typedef CPError (STDCALL *CP_VersionNegotiateFunc)( | |
| 551 uint16 min_version, uint16 max_version, uint16 *selected_version); | |
| 552 | |
| 553 // 'bfuncs' are the browser functions provided to the plugin. 'id' is the | |
| 554 // plugin identifier that the plugin should use when calling browser functions. | |
| 555 // The plugin should initialize 'pfuncs' with pointers to its own functions, | |
| 556 // or return an error code. | |
| 557 // All functions and entry points should be called on the same thread. The | |
| 558 // plugin should not attempt to call a browser function from a thread other | |
| 559 // than the one CP_InitializeFunc is called from. | |
| 560 typedef CPError (STDCALL *CP_InitializeFunc)( | |
| 561 CPID id, const CPBrowserFuncs* bfuncs, CPPluginFuncs* pfuncs); | |
| 562 | |
| 563 #ifdef __cplusplus | |
| 564 } // extern "C" | |
| 565 #endif | |
| 566 | |
| 567 #endif // CHROME_COMMON_CHROME_PLUGIN_API_H_ | |
| OLD | NEW |