Overview

High-level look at the services available to developers using Epic Online Services.

Design Philosophy

We designed Epic Online Services (EOS) SDK from the ground up to be as portable as possible across both hardware and software platforms. It is currently available for desktop platforms, with additional platforms planned for the near future. Integrations for both Unreal Engine 4 and Unity will become available at a later date.

Stable ABI

We wrote the EOS SDK interface in C to provide a stable application binary interface (ABI). This ensures that regardless of which compiler you choose, the implementation, including calling conventions, data sizes, and memory alignment, is guaranteed to work for any application software that integrates with it.

Adhering to this convention makes it possible to patch the SDK code independently from the game client. Distributing fixes and updates without recompiling the application is important to maintaining the SDK over its lifetime.

Finally, focusing on C enforces a more deliberate exposure of the public API.

Versioning

Versioning is fundamental to the EOS SDK. Its use of versioning guarantees backward compatibility with games that use older versions of the SDK, even if the API changes. Every interface, function, and data type has a version associated with it. When a new SDK version is released, that SDK will recognize and support older versions and react appropriately to data and function calls coming from them. This may include calling the original version of the function internally, migrating the original input structures to newer forms, or setting up reasonable defaults where possible. All of this means that older games using the SDK do not have to release updates to maintain compatibility with EOS.

Interface Handles

Modular, service-specific interfaces group supported features together. For example, the Auth Interface handles authenticating user credentials within Epic's ecosystem, the Friends Interface handles everything related to managing your friends list, and so on.

The EOS SDK exposes its interfaces through opaque handles, which are provided by the Platform Interface. An interface handle's lifetime lasts as long as the Platform Interface itself, and is required as the first parameter to every API function using that interface.

Naming Conventions

All EOS SDK interfaces use consistent naming conventions to help communicate usage and intent. When the following verbs appear in function names, they imply specific behaviors, as follows:

Verb

Meaning

Create

The function allocates memory and expects to be paired with a "Release" function.

Release

The function frees memory. These have a corresponding "Create" function.

Query

Interacts with backend services asynchronously, over an unspecified period of time. These calls may be throttled or retried depending on connectivity.

Get

Retrieves cached data from a previous call to a Query function.

Function Signatures

Every function in the EOS SDK has a very similar signature. In addition to function names adhering to the scheme described above, function parameters follow a predictable pattern. The first parameter is always the handle for the relevant interface, followed by an "options" data structure that encapsulates all of the function's parameters and contains API versioning information. Finally, asynchronous functions will also feature an application-specific callback function, and may additionally accept user-defined context information for the callback function to process. This callback function will always run when the asynchronous operation ultimately succeeds or fails, and may also run in response to delays caused by connectivity issues.

Error Handling

Error codes from EOS SDK functions use the type EOS_EResultEOS_EResult. This type includes both common error values and errors specific to a single interface. Common errors take the form EOS_<ErrorCode>, while interface-specific error codes appear as EOS<em><Interface></em><ErrorCode>. Some examples follow:

Verb

Meaning

EOS_InvalidParameters

There was at least one unset or invalid input parameter passed to the function.

EOS_InvalidUser

The operation requires a user, but the provided user was invalid or unspecified.

EOS_MissingPermissions

The backend system rejected the request due to access restrictions.

EOS_UnrecognizedResponse

The SDK was unable to parse the backend's response.

EOS_OperationWillRetry

Backend connectivity is impaired and the SDK will try again.

EOS_IncompatibleVersion

The API version parameter that the calling code sent does not match the function's version number in the SDK.

EOS_Auth_TokenInvalid

Specific to the Auth Interface, the local authentication session has expired or become invalid, and the user needs to log in again.

Strings

Strings, both as input and as output, are expected to be in UTF-8 form.

Memory Allocation

When an SDK function needs to provide a data structure to a callback, the SDK allocates the memory for the data, and frees the memory as soon as the callback function completes. If you need to cache a copy of that data, you must make your copy during the lifetime of the callback function. In addition, if your system requires custom memory allocators, you can specify them at SDK creation time.

SDK Functions with the verb "get" in their names also own the memory they use. Like callbacks, you must make a copy of the data if you want to have access to it later.

SDK Functions with the verb "copy" in their names are the exception. These functions return copies of cached data, and expect that the caller takes ownership of the copy. The SDK will never free the copy, so the user must call the corresponding "release" function before shutting the SDK down.