Pepper API Best Practices

When appropriate, suffix enumeration constants with _PRIVATE.

Two enum constants can't have the same name, so making a separate enum for

Private constants causes trouble. Suffixing the constants with _PRIVATE makes

it clear which values are public and which are private. This also keeps names

from colliding.

Use primitive types in C interfaces when possible.

It's easier for users to deal with primitive types (int, double, etc.) than

PP_Var. This is worth doing, even when trying to make an interface mirror a

JavaScript counterpart. If a string must be valid UTF-8, use PP_Var.

Be extra careful with C++ interfaces.

We don't have any mechanism today to provide multiple versions of a C++

interface to users. This means we must be even more forward-looking about what

is in those APIs, as libraries may come to depend on them.

In C++ implementations, always call the newest reasonable C interface.

Code in ppapi/cpp/ should check for the available C versions and always call

the newest available version that works for the given parameters. This makes it

more feasible to deprecate or remove a version of the C interface at some point

in the future.

Don't pass structs by value.

This can cause API breakage because PNaCl may change calling conventions on

different platforms.

Follow existing reference counting conventions.

When passing PP_Resource or PP_Var as an input parameter to an API, the API

should not expect to be passed a reference. It should explicitly take a

reference if it needs to.

Return values and output parameters must pass a reference back to the caller.

This includes output parameters for calls that return asynchronously via a

CompletionCallback.

Follow existing PP_CompletionCallback conventions.

Functions that take a completion callback should:

• Return int32_t, which must be either a positive value or a value from

ppapi/c/pp_errors.h

• Take only 1 PP_CompletionCallback parameter.

• Run the PP_CompletionCallback exactly once.

Use the Enter* classes and TrackedCallback to ensure the behavior is

consistent.

Provide all new PPP interfaces as a parameter to a PPB interface.

Legacy PPP interfaces are exposed via the Plugin's GetInterface call and are

associated with an interface string, much like PPB interfaces. This has two

drawbacks:

• It's hard to associate a particular version of a PPB interface with its

corresponding PPP interface.

• We can only ever call the PPP interface on the main thread.

Design your API to be friendly as a porting layer for a more well-known API.

Our FileIO API should make it easy to implement POSIX file operations.

Similarly, our sockets APIs should make it possible to implement BSD/POSIX

sockets.