ppapi/api/ppp.idl

   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
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines three functions that your module must
   8  * implement to interact with the browser.
   9  */
  10
  11 #inline c
  12
  13 #include "ppapi/c/pp_module.h"
  14 #include "ppapi/c/pp_stdint.h"
  15 #include "ppapi/c/ppb.h"
  16
  17 #if __GNUC__ >= 4
  18 #define PP_EXPORT __attribute__ ((visibility("default")))
  19 #elif defined(_MSC_VER)
  20 #define PP_EXPORT __declspec(dllexport)
  21 #endif
  22
  23 /* {PENDING: undefine PP_EXPORT?} */
  24
  25 /* We don't want name mangling for these external functions.  We only need
  26  * 'extern "C"' if we're compiling with a C++ compiler.
  27  */
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * @addtogroup Functions
  34  * @{
  35  */
  36
  37 /**
  38  * PPP_InitializeModule() is the entry point for a module and is called by the
  39  * browser when your module loads. Your code must implement this function.
  40  *
  41  * Failure indicates to the browser that this module can not be used. In this
  42  * case, the module will be unloaded and ShutdownModule will NOT be called.
  43  *
  44  * @param[in] module A handle to your module. Generally you should store this
  45  * value since it will be required for other API calls.
  46  * @param[in] get_browser_interface A pointer to the function that you can
  47  * use to query for browser interfaces. Generally you should store this value
  48  * for future use.
  49  *
  50  * @return <code>PP_OK</code> on success. Any other value on failure.
  51  */
  52 PP_EXPORT int32_t PPP_InitializeModule(PP_Module module,
  53                                        PPB_GetInterface get_browser_interface);
  54 /**
  55  * @}
  56  */
  57
  58 /**
  59  * @addtogroup Functions
  60  * @{
  61  */
  62
  63 /**
  64  * PPP_ShutdownModule() is <strong>sometimes</strong> called before the module
  65  * is unloaded. It is not recommended that you implement this function.
  66  *
  67  * There is no practical use of this function for third party modules. Its
  68  * existence is because of some internal use cases inside Chrome.
  69  *
  70  * Since your module runs in a separate process, there's no need to free
  71  * allocated memory. There is also no need to free any resources since all of
  72  * resources associated with an instance will be force-freed when that instance
  73  * is deleted.
  74  *
  75  * <strong>Note:</strong> This function will always be skipped on untrusted
  76  * (Native Client) implementations. This function may be skipped on trusted
  77  * implementations in certain circumstances when Chrome does "fast shutdown"
  78  * of a web page.
  79  */
  80 PP_EXPORT void PPP_ShutdownModule(void);
  81 /**
  82  * @}
  83  */
  84
  85 /**
  86  * @addtogroup Functions
  87  * @{
  88  */
  89
  90 /**
  91  * PPP_GetInterface() is called by the browser to query the module for
  92  * interfaces it supports.
  93  *
  94  * Your module must implement the <code>PPP_Instance</code> interface or it
  95  * will be unloaded. Other interfaces are optional.
  96  *
  97  * This function is called from within browser code whenever an interface is
  98  * needed. This means your plugin could be reentered via this function if you
  99  * make a browser call and it needs an interface. Furthermore, you should not
 100  * make any other browser calls from within your implementation to avoid
 101  * reentering the browser.
 102  *
 103  * As a result, your implementation of this should merely provide a lookup
 104  * from the requested name to an interface pointer, via something like a big
 105  * if/else block or a map, and not do any other work.
 106  *
 107  * @param[in] interface_name A pointer to a "PPP" (plugin) interface name.
 108  * Interface names are null-terminated ASCII strings.
 109  *
 110  * @return A pointer for the interface or <code>NULL</code> if the interface is
 111  * not supported.
 112  */
 113 PP_EXPORT const void* PPP_GetInterface(const char* interface_name);
 114 /**
 115  * @}
 116  */
 117
 118 #ifdef __cplusplus
 119 }  /* extern "C" */
 120 #endif
 121
 122 #endinl
 123
 124 /**
 125  * Defines the type of the <code>PPP_InitializeModule</code> function.
 126  */
 127 typedef int32_t PP_InitializeModule_Func(
 128     [in] PP_Module module,
 129     [in] PPB_GetInterface get_browser_interface);
 130
 131 /**
 132  * Defines the type of the <code>PPP_ShutdownModule</code> function.
 133  */
 134 typedef void PP_ShutdownModule_Func();
 135
 136 /**
 137  * Defines the type of the <code>PPP_ShutdownModule</code> function.
 138  */
 139 typedef interface_t PP_GetInterface_Func([in] str_t interface_name);