ManualWebService

GameCreate includes a number of web services that can be used to manipulate your GameCreate domain. With GameCreate's web services, you can perform the following tasks:

Using GameCreate as the base service, it is possible to build software to perform a variety of tasks such as renting permanent servers to users, or run competitions using GameCreate's temporary servers as the location of matches.

Our web services use SOAP over HTTP. [WWW] http://webservices.xml.com/pub/a/ws/2001/04/04/webservices/ is an introduction to web services.

GameCreate supplies three individual services each with a number of different methods. The three service categories are:

For each category, we will supply the link to the WSDL and then discuss each of the methods supported by that web service.

Users

The Users web service allows you to create, modify, or lookup user information in the GameCreate account system. The web service can not access information for domains using external authentication (see Manual External Authentication). If your domain uses external authentication then you will need to build the required functionality into your own account system.

The WSDL for the service is located at [WWW] http://world.gamecreate.com/admin/User.asmx?wsdl . Requests must be sent to http://yourdomain.cc.gamecreate.com/admin/User.asmx - that is, the same domainname as you see after logging into GameCreate. For example, Mammoth Media might use http://mammoth.au.gamecreate.com/admin/User.asmx . It is important you use the correct /admin/User.asmx as this allows GameCreate to identify your domain.

Test Login/Retrieve a user's Unique ID

int Login(string username, string password);

GameCreate will look in its account system for the specified user and see if the password is correct. If it is, GameCreate will return the unique ID identifying the user. If the password is incorrect (or the specified username does not identify a user) GameCreate will return 0.

Create an account

int CreateAccount(string username, string password, string name, string email);

GameCreate will attempt to create a user account with the provided username, password, name, and email address. If the specified username is already assigned to another user or an error occurs, GameCreate returns 0. If the new user is created successfully, GameCreate returns the Unique ID of the created user.

Note that you should not store the username as an identifier - usernames can be changed by the user. The correct identifier to use is the Unique ID returned by the web service.

Test if username is taken

bool IsUsernameAvailable(string username);

If the specified username is not assigned to a user at the time of the request GameCreate returns true. If the username is taken by another user, GameCreate returns false.

Note that a return value of true does not imply that a later call to Create Account() will definately succeed; the username may be taken between the two calls. Always check the result of CreateAccount(...) to see if a user was created successfully.

Update existing account details

bool UpdateAccount(string currentUsername, string currentPassword, string username, string password, string name, string email);

Update the details of an existing GameCreate user account. currentUsername and currentPassword are the login details for the user to update. username, password, name, email are the new details for the user. Any of these four values can be the empty string to indicate no change is required.

If currentUsername and currentPassword are not a valid user login, GameCreate returns false.

If currentUsername and currentPassword are a valid user login, but username is already in use by another user, GameCreate returns false. Any of the other requested changes (password, name, email) will not be processed.

If GameCreate successfully performs the requested updates, GameCreate returns true.

Retrieve user information

UserDetails GetAccount(string username, string password);

Retrieve the details for the user identified by the supplied username and password. If the supplied details are invalid, GameCreate will return no data.

The User Details structure has the following form: 

UserDetails {
  string Username;
  string Name;
  string Email;
}

Permanent Servers and Subdomains

The Permanent Servers and Subdomains web service allows you to create, modify, or lookup permanent servers and subdomains in GameCreate. You can also assign users permission to access various areas in GameCreate.

The WSDL for the service is located at [WWW] http://world.gamecreate.com/admin/Remote.asmx?wsdl . Requests must be sent to http://yourdomain.cc.gamecreate.com/admin/Remote.asmx - that is, the same domainname as you see after logging into GameCreate. For example, Mammoth Media might use http://mammoth.au.gamecreate.com/admin/Remote.asmx . It is important you use the correct /admin/Remote.asmx as this allows GameCreate to identify your domain.

Many of the methods in this web service require a domain ID. The domain ID for your domain can be found in the Domain area of GameCreate.com. Alternatively, the domain ID can be for a subdomin of your domain - either as listed in the Domain area or as returned from the CreateSubdomain(...) method detailed below.

Create a subdomain

int CreateSubdomain(string actorUsername, string actorPassword, string name, string uniquename);

Create a subdomain of your domain. actorUsername and actorPassword identify a user who has permission to create subdomains. name is the name of the new subdomain.

uniquename is the name used to form the domain name for the new subdomain. If the GameCreate URL for your domain is [WWW] http://yourdomain.cc.gamecreate.com/admin/ , the URL for the new subdomain will be [WWW] http://uniquename.yourdomain.cc.gamecreate.com/admin/ .

GameCreate returns 0 if it was unable to create the new subdomain. This can occur if the specified actor is invalid or does not have the required permission, or if the uniquename is already in use by some other subdomain.

GameCreate returns the Unique ID for the subdomain upon success.

Give user permissions on a subdomain

bool SetUserDomainPermissions(string actorUsername, string actorPassword, int domainid, int userid, int permissionType);

Gives a user permission to access a subdomain. domainid identifies the domain and userid is the Unique ID of the user (as returned by the Users web service). actorUsername and actorPassword is a valid login for a user who has the domain administrator permission.

permissionType is created by selecting one or more of the following values and adding them together:

Install game software

bool InstallGame(string actorUsername, string actorPassword, int domainid, int gameid, int hostid);

Installs a game on a host for. domainid identifies the domain. gameid identifies the game to install (see Manual Xml Status for information on determining game IDs). hostid identifies the host to install (see Manual Xml Status for information on determining host IDs).

actorUsername and actorPassword are the login information for a user in the subdomain who has permission to perform the requested installation.

GameCreate returns true if the installation request succeeded. GameCreate returns false if the game ID is invalid, the host ID is invalid, the actor is invalid, or the actor does not have the required permission.

Just like when using the GameCreate website, this method simply requests GameCreate to perform the software installation: it does not wait for the installation to complete before returning the result code. The installation will be completed independent of the web service without further intervention on your behalf.

Create a game server

int CreateServer(string actorUsername, string actorPassword, int domainid, int gameid, int hostid, string name, int players);

Creates a permanent game server in a subdomain. domainid identifies the subdomain. gameid identifies the game type for the server (see Manual Xml Status for information on determining game IDs). hostid identifies the host to place the game server on (see Manual Xml Status for information on determining host IDs).

name is the name for the new server and players is the maximum players for the new server.

actorUsername and actorPassword are the login information for a user in the subdomain who has permission to create the new server.

GameCreate returns a unique ID for the new server if the request succeeded. GameCreate returns 0 if the game ID is invalid, the host ID is invalid, the actor is invalid, or the actor does not have the required permission.

Just like when using the GameCreate website, this method simply creates the server within GameCreate: it does not wait for the server to be physically started on the host by GameCreate.

Set user permissions on a server

bool SetUserServerPermissions(string actorUsername, string actorPassword, int domainid, int userid, int serverid, int permissionType);

Gives a user permission on a particular server. domainid identifies the domain and userid is the Unique ID of the user (as returned by the Users web service).

actorUsername and actorPassword is a valid login for a user who has the server administrator permission. serverid is the Unique ID of a server (ie, as returned by an earlier CreateServer(...) call or by looking up a server via Manual Xml Status).

permissionType is created by selecting one or more of the following values and adding them together:

GameCreate returns true if the requested permission was set. GameCreate returns false if the server ID is invalid, the user ID is invalid, the actor is invalid, or the actor does not have the required permission.

Set user permissions on a game

bool SetUserGamePermissions(string actorUsername, string actorPassword, int domainid, int userid, int gameid, int permissionType);

Gives a user permission on a particular game; this is useful to let the user modify existing or create new properties. domainid identifies the domain and userid is the Unique ID of the user (as returned by the Users web service).

actorUsername and actorPassword is a valid login for a user who has the game administrator permission. gameid is the Unique ID of a game (ie, by looking up a game via Manual Xml Status).

permissionType is created by selecting one or more of the following values and adding them together:

GameCreate returns true if the requested permission was set. GameCreate returns false if the game ID is invalid, the user ID is invalid, the actor is invalid, or the actor does not have the required permission.

Restart an existing server

bool RestartServer(string actorUsername, string actorPassword, int domainid, int serverid);

Restart a particular game server. domainid identifies the domain and serverid is the Unique ID of a server (ie, as returned by an earlier CreateServer(...) call or by looking up a server via Manual Xml Status).

actorUsername and actorPassword is a valid login for a user who has the server control permission.

GameCreate returns true if the server will be restarted. GameCreate returns false if the server ID is invalid, the actor is invalid, or the actor does not have the required permission.

This method will return 'true' before the game server has been restarted. The restart will be performed as soon as the server's host is able to do so.

Start or stop a server

bool SetServerRunning(string actorUsername, string actorPassword, int domainid, int serverid, int running);

Starts or stops a particular game server. domainid identifies the domain and serverid is the Unique ID of a server (ie, as returned by an earlier CreateServer(...) call or by looking up a server via Manual Xml Status).

actorUsername and actorPassword is a valid login for a user who has the server control permission. running can be one of two values:

GameCreate returns true if the server status was able to be set (even if there is no change). GameCreate returns false if the server ID is invalid, the actor is invalid, or the actor does not have the required permission.

This method returns 'true' before the server is physically started or stopped. The server will be started or stopped as soon as the server's host is able to do so.

Alter a server's maximum player limit

bool SetServerPlayerCount(string actorUsername, string actorPassword, int domainid, int serverid, int players);

Changes the player limit on a game server. domainid identifies the domain and serverid is the Unique ID of a server (ie, as returned by an earlier CreateServer(...) call or by looking up a server via Manual Xml Status).

actorUsername and actorPassword is a valid login for a user who has the server write players permission. players is the new maximum player limit for the server.

GameCreate returns true if the server player limit was able to be set (even if there is no change). GameCreate returns false if the server ID is invalid, the actor is invalid, or the actor does not have the required permission.

A change in player limit will not take effect the game server is next (re)started.

Retrieve a server's current status

ServerStatus GetServerStatus(string actorUsername, string actorPassword, int domainid, int serverId);

Retrieves a server's current status, such as its processor usage and memory consumption. In general use of Manual Xml Status is preferable to this method call as it is faster. This method should only be used in circumstances such as displaying information for a single server in response to a user's request.

domainid identifies the domain and serverid is the Unique ID of a server (ie, as returned by an earlier CreateServer(...) call or by looking up a server via Manual Xml Status).

actorUsername and actorPassword is a valid login for a user who has the server read permission.

GameCreate returns nothing if the server ID is invalid, the actor is invalid, or the actor does not have the required permission. Otherwise, the following information is returned: 

ServerStatus {
  int PlayerCount; // Number of players currently on server
  int MaxPlayers; // Maximum player limit for the server
  int CurrentMemory; // Current amount of memory being consumed by the server (in kilobytes)
  float CpuUsage; // Processor usage on the server's host, expressed as a percentage over the total processor availability
}

Delete a server

bool DeleteServer(string actorUsername, string actorPassword, int domainid, int serverId);

Deletes an existing server - the server must be stopped before it can be deleted. domainid identifies the domain and serverid is the Unique ID of a server (ie, as returned by an earlier CreateServer(...) call or by looking up a server via Manual Xml Status).

actorUsername and actorPassword is a valid login for a user who has the server delete permission.

GameCreate returns true if the server was deleted. GameCreate returns false if the server ID is invalid, the actor is invalid, the server is not in the 'Stopped' state, or the actor does not have the required permission.

Check if game software is installed

bool IsGameInstalled(string actorUsername, string actorPassword, int domainid, int gameid, int hostid);

Determines if a game is installed on a host. domainid identifies the domain. gameid identifies the game to install (see Manual Xml Status for information on determining game IDs). hostid identifies the host to install (see Manual Xml Status for information on determining host IDs).

actorUsername and actorPassword are the login information for a user in the subdomain who has permission to determine if the software is installed.

GameCreate returns true if the software is installed. GameCreate returns false if the game is not installed on the host, the game ID is invalid, the host ID is invalid, the actor is invalid, or the actor does not have the required permission.

Temporary Servers

The Temporary Servers web service allows you to create, modify, or lookup temporary servers in GameCreate. Many of the methods in this web service talk about a server's owner. The owner is the user who initially created the temporary server (note that permanent servers do not have owners).

This service was designed to be used on its own, so there is some overlap functionality-wise with the "Permanent Servers and Subdomains" web service.

The WSDL for the service is located at [WWW] http://world.gamecreate.com/bookings/MakeBooking.asmx?wsdl . Requests must be sent to http://yourdomain.cc.gamecreate.com/bookings/MakeBooking.asmx - that is, the same domainname as you see after logging into GameCreate. For example, Mammoth Media might use http://mammoth.au.gamecreate.com/bookings/MakeBooking.asmx . It is important you use the correct /bookings/MakeBooking.asmx as this allows GameCreate to identify your domain.

Some methods in this web service deal with starting time for the servers. Times are always represented as UNIX timestamps - that is, the number of seconds that have elapsed since 1970-01-01 0:00:00 UTC. (For that reason, all timestamps are implicitly in UTC).

Some methods use a "query string" style collection of property variable/value names. This deserves some explanation. GameCreate's game properties have something called a "variable" - an example being rcon_password. The variable name is used in configuration files like %rcon_password%. A "query string" style collection is formed by:

As a concrete example, supposed we wanted to supply two values: an RCON password of "test" and a Time Limit of "30". Having consulted the game's Properties page, we determine the variable names for those properties are "rcon_password" and "timelimit". Performing the three steps listed above, we end up with the final string of "rcon%5Fpassword=test&timelimit=30".

Check time availability

bool IsServerAvailableAtTime(string username, string password, int gameId, int startTimestamp, int runtimeMins, int numberPlayers);

Determines if a server could be created at a particular time. Note that a true result here does not guarantee a call to CreateServer(...) will succeed, as other servers may be created between the two method calls.

username and password identify the user to perform the check as. This is required as this method also checks against the user's weekly server limit, and will return false if the specified time would be available but would exceed the user's limit.

gameId specifies the unique ID of the server's intended game type (see Manual Xml Status for information on determining game IDs). numberPlayers is the desired maximum player limit for the server.

startTimestamp is the UNIX timestamp identifying the desired starting time. runtimeMins is the number of minutes the temporary server would be required to run for.

GameCreate returns true if the user could create a temporary server with the specified options. GameCreate returns false if a temporary server with the specified options could not be created , or if the specified user details were not valid.

Create a temporary server

int CreateServer(string username, string password, int gameId, int startTimestamp, int runtimeMins, int numberPlayers, string name, string propertyValues, string templateIds);

Creates a server's at the requested time with the supplied name, property values, and templates. username and password identify the user who will be the owner of the server. gameId specifies the unique ID of the server's game type (see Manual Xml Status for information on determining game IDs).

startTimestamp is the UNIX timestamp identifying the starting time. runtimeMins is the number of minutes the temporary server will run for.

name is the server's name. propertyValues is a "query string" style collection of propery variable/value pairs. templateIds is a comma-separated list of game template IDs.

GameCreate returns a unique ID for the new server if the temporary server was created. GameCreate returns <= 0 if a temporary server with the specified options could not be created , or if the specified user details were not valid.

Get starting time for server

int GetServerStartTimestamp(int serverId);

This method is only for temporary servers.

Retrieves the time the specified server is scheduled to start, as a UNIX timestamp. serverId is the unique ID of the server (as returned by CreateServer(...) or obtained via Manual Xml Status).

No specific permissions are required to retrieve the start time.

Send server details to users

public bool EmailServerDetails(string username, string password, int serverId, string[] addresses, bool includeSecretProperties);

Send a message containing details about the server to the specified email addresses. username and password identify the user who is the owner of the server .

serverId is the unique ID of the server (as returned by CreateServer(...) or obtained via Manual Xml Status). addresses is a list of email addresses. Each email address will receive one email.

Each game property has a 'Secret' setting indicating if the property's value should be hidden from normal users ('RCON Password' is a common example of a secret property). 'Client Password' is generally not a secret property as everyone needs it to play. includeSecretProperties determines if secret game properties will be emailed to the specified addresses.

GameCreate returns true if the emails were sent. GameCreate returns false if the specified user account is not valid, the specified server does not exist, or the user does not own the temporary server.

Modify server

bool ModifyServer(string username, string password, int serverId, string name, string propertyValues, string templateIds);

Modify a server's name, property values, and templates. username and password identify the user who is the owner of the server. serverId is the unique ID of the server (as returned by CreateServer(...) or obtained via Manual Xml Status).

name is the server's new name. propertyValues is a "query string" style collection of propery variable/value pairs. templateIds is a comma-separated list of game template IDs.

GameCreate returns true if the server was modified. GameCreate returns false if the specified user account is not valid, the specified server does not exist, or the user does not own the temporary server.

Delete a server

bool DeleteServer(string username, string password, int serverId);

Deletes a server owned by the specified user (note that the 'Permanent Servers and Subdomains' web service has a more general Delete Server method). The temporary server must not be running (such as before it has started).

username and password identify the user who is the owner of the server. serverId is the unique ID of the server (as returned by CreateServer(...) or obtained via Manual Xml Status).

GameCreate returns true if the server was deleted. GameCreate returns false if the specified user account is not valid, the specified server does not exist, the user does not own the temporary server, or it is running.

last edited 2006-02-06 07:05:46 by NathanOsullivan

© Mammoth Media 2001-2007.
GameCreate™ is a trademark of Mammoth Media Pty Ltd. GameCreate® is a registered trademark in Australia.