OLD | NEW |
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef PPAPI_CPP_INSTANCE_H_ | 5 #ifndef PPAPI_CPP_INSTANCE_H_ |
6 #define PPAPI_CPP_INSTANCE_H_ | 6 #define PPAPI_CPP_INSTANCE_H_ |
7 | 7 |
8 /// @file | 8 /// @file |
9 /// This file defines the C++ wrapper for an instance. | 9 /// This file defines the C++ wrapper for an instance. |
10 | 10 |
(...skipping 15 matching lines...) Expand all Loading... |
26 struct PP_InputEvent; | 26 struct PP_InputEvent; |
27 | 27 |
28 /// The C++ interface to the Pepper API. | 28 /// The C++ interface to the Pepper API. |
29 namespace pp { | 29 namespace pp { |
30 | 30 |
31 class Compositor; | 31 class Compositor; |
32 class Graphics2D; | 32 class Graphics2D; |
33 class Graphics3D; | 33 class Graphics3D; |
34 class InputEvent; | 34 class InputEvent; |
35 class InstanceHandle; | 35 class InstanceHandle; |
| 36 class MessageHandler; |
| 37 class MessageLoop; |
36 class Rect; | 38 class Rect; |
37 class URLLoader; | 39 class URLLoader; |
38 class Var; | 40 class Var; |
39 | 41 |
40 class Instance { | 42 class Instance { |
41 public: | 43 public: |
42 /// Default constructor. Construction of an instance should only be done in | 44 /// Default constructor. Construction of an instance should only be done in |
43 /// response to a browser request in <code>Module::CreateInstance</code>. | 45 /// response to a browser request in <code>Module::CreateInstance</code>. |
44 /// Otherwise, the instance will lack the proper bookkeeping in the browser | 46 /// Otherwise, the instance will lack the proper bookkeeping in the browser |
45 /// and in the C++ wrapper. | 47 /// and in the C++ wrapper. |
(...skipping 442 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
488 /// further information. | 490 /// further information. |
489 /// | 491 /// |
490 /// Refer to HandleMessage() for receiving events from JavaScript. | 492 /// Refer to HandleMessage() for receiving events from JavaScript. |
491 /// | 493 /// |
492 /// @param[in] message A <code>Var</code> containing the data to be sent to | 494 /// @param[in] message A <code>Var</code> containing the data to be sent to |
493 /// JavaScript. Message can have a numeric, boolean, or string value. | 495 /// JavaScript. Message can have a numeric, boolean, or string value. |
494 /// Array/Dictionary types are supported from Chrome M29 onward. | 496 /// Array/Dictionary types are supported from Chrome M29 onward. |
495 /// All var types are copied when passing them to JavaScript. | 497 /// All var types are copied when passing them to JavaScript. |
496 void PostMessage(const Var& message); | 498 void PostMessage(const Var& message); |
497 | 499 |
| 500 /// Dev-Channel Only |
| 501 /// |
| 502 /// Registers a handler for receiving messages from JavaScript. If a handler |
| 503 /// is registered this way, it will replace the Instance's HandleMessage |
| 504 /// method, and all messages sent from JavaScript via postMessage and |
| 505 /// postMessageAndAwaitResponse will be dispatched to |
| 506 /// <code>message_handler</code>. |
| 507 /// |
| 508 /// The function calls will be dispatched via <code>message_loop</code>. This |
| 509 /// means that the functions will be invoked on the thread to which |
| 510 /// <code>message_loop</code> is attached, when <code>message_loop</code> is |
| 511 /// run. It is illegal to pass the main thread message loop; |
| 512 /// RegisterMessageHandler will return PP_ERROR_WRONG_THREAD in that case. |
| 513 /// If you quit <code>message_loop</code> before calling Unregister(), |
| 514 /// the browser will not be able to call functions in the plugin's message |
| 515 /// handler any more. That could mean missing some messages or could cause a |
| 516 /// leak if you depend on Destroy() to free hander data. So you should, |
| 517 /// whenever possible, Unregister() the handler prior to quitting its event |
| 518 /// loop. |
| 519 /// |
| 520 /// Attempting to register a message handler when one is already registered |
| 521 /// will cause the current MessageHandler to be unregistered and replaced. In |
| 522 /// that case, no messages will be sent to the "default" message handler |
| 523 /// (pp::Instance::HandleMessage()). Messages will stop arriving at the prior |
| 524 /// message handler and will begin to be dispatched at the new message |
| 525 /// handler. |
| 526 /// |
| 527 /// @param[in] message_handler The plugin-provided object for handling |
| 528 /// messages. The instance does not take ownership of the pointer; it is up |
| 529 /// to the plugin to ensure that |message_handler| lives until its |
| 530 /// WasUnregistered() function is invoked. |
| 531 /// @param[in] message_loop Represents the message loop on which |
| 532 /// MessageHandler's functions should be invoked. |
| 533 /// @return PP_OK on success, or an error from pp_errors.h. |
| 534 int32_t RegisterMessageHandler(MessageHandler* message_handler, |
| 535 const MessageLoop& message_loop); |
| 536 |
| 537 /// Unregisters the current message handler for this instance if one is |
| 538 /// registered. After this call, the message handler (if one was |
| 539 /// registered) will have "WasUnregistered" called on it and will receive no |
| 540 /// further messages. After that point, all messages sent from JavaScript |
| 541 /// using postMessage() will be dispatched to pp::Instance::HandleMessage() |
| 542 /// on the main thread. Attempts to call postMessageAndAwaitResponse() from |
| 543 /// JavaScript after that point will fail. |
| 544 /// |
| 545 /// Attempting to unregister a message handler when none is registered has no |
| 546 /// effect. |
| 547 void UnregisterMessageHandler(); |
| 548 |
498 /// @} | 549 /// @} |
499 | 550 |
500 /// @{ | 551 /// @{ |
501 /// @name PPB_Console methods for logging to the console: | 552 /// @name PPB_Console methods for logging to the console: |
502 | 553 |
503 /// Logs the given message to the JavaScript console associated with the | 554 /// Logs the given message to the JavaScript console associated with the |
504 /// given plugin instance with the given logging level. The name of the plugin | 555 /// given plugin instance with the given logging level. The name of the plugin |
505 /// issuing the log message will be automatically prepended to the message. | 556 /// issuing the log message will be automatically prepended to the message. |
506 /// The value may be any type of Var. | 557 /// The value may be any type of Var. |
507 void LogToConsole(PP_LogLevel level, const Var& value); | 558 void LogToConsole(PP_LogLevel level, const Var& value); |
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
581 private: | 632 private: |
582 PP_Instance pp_instance_; | 633 PP_Instance pp_instance_; |
583 | 634 |
584 typedef std::map<std::string, void*> InterfaceNameToObjectMap; | 635 typedef std::map<std::string, void*> InterfaceNameToObjectMap; |
585 InterfaceNameToObjectMap interface_name_to_objects_; | 636 InterfaceNameToObjectMap interface_name_to_objects_; |
586 }; | 637 }; |
587 | 638 |
588 } // namespace pp | 639 } // namespace pp |
589 | 640 |
590 #endif // PPAPI_CPP_INSTANCE_H_ | 641 #endif // PPAPI_CPP_INSTANCE_H_ |
OLD | NEW |