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
29extern "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 */
52PP_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 */
80PP_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 */
113PP_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 */
127typedef 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 */
134typedef void PP_ShutdownModule_Func();
135
136/**
137 * Defines the type of the <code>PPP_ShutdownModule</code> function.
138 */
139typedef interface_t PP_GetInterface_Func([in] str_t interface_name);
140