src/ppapi/c/ppp.h

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