Developer Reference

Using Templated Class DB Handler

This is the newest Method in which modders can interact with the Universal API's MongoDB Endpoints providing access to modders to be able to build mods that utilize the Universal API Webservice.

• oid is the Object ID or Player ID(Can Use Steam64id or GUID)

Steam64ID's are converted to the GUID when it hits the API

class UApiDBHandler<Class T> extends UApiDBHandlerBase

Simple example on how you could use it

autoptr UApiDBHandler<myClass> m_MyModHandler = new UApiDBHandler<myClass>("MyMod", PLAYER_DB); //PLAYER_DB or OBJECT_DB
m_MyModHandler.Save("GUID", myObject);
m_MyModHandler.Load("GUID", player, "CBMyCallBackFunction"); 

NOTE

All functions return a int matching the call back function id which can be used to cancel the call back using UApi().RequestCallCancel(callId) to stop the call back function from running this is useful as call backs on NULL instances can cause access violations so make sure you track and cancel call backs on object destruction

Saving And Loading Data

Lets you save and load data to the api/database

• Save Works Server Side Only
• Load On PlayerDB only works on client for the player the auth key was issued for.
• Load On ObjectDB works both client and server

int Save(string oid, Class object){}
int Save(string oid, Class object, Class cbInstance, string cbFunction){}

//Load allows you to pass default Object/Json in order to create the object if it doesn't exist (only works on server)
int Load(string oid, Class cbInstance, string cbFunction, string defaultJson = "{}"){}
int Load(string oid, Class cbInstance, string cbFunction, Class defaultObject){}

Load and Save Callback function

protected void CBMyCallBackFunction(int cid, int status, string oid, myClass data) {
   if ( status == UAPI_SUCCESS ){
      //Do something with data
   }
}

Load Json

Works just like load but returns json string instead of the object incase you want a bit more control on loading

int LoadJson(string oid, Class cbInstance, string cbFunction, string defaultJson = "{}"){}

Load Json Callback Function

protected void CBMyCallBackFunction(int cid, int status, string guid, string data) {
   if ( status == UAPI_SUCCESS ){
      //Do something with data you use 
      autoptr myClass obj;
      if (UApiJSONHandler<myClass>.FromString(data, obj)){
         
      }
   }
}

Transactions

Updates a sub value inside the object in the database then returns the new value only works with floats or ints Sub objects can be used with dot notation aka MySubObject.SubObjectVar Will return status of UAPI_SUCCESS if operations was successful

• Only works on server

int Transaction(string oid, string element, float value){}
int Transaction(string oid, string element, float value, Class cbInstance, string cbFunction){} //Returns type UApiTransactionResponse

Transactions Call back function

protected void CBMyCallBackFunction(int cid, int status, string guid, UApiTransactionResponse data) {
   if ( status == UAPI_SUCCESS ){
      //Value Updated Successfully
      float newValue = data.Value;
   }
}

Update Functions

Updates a sub value inside the object in the database, can also use other operations https://github.com/daemonforge/DayZ-UniveralApi/blob/master/_UniversalApi/scripts/1_Core/Constants.c#L30 Values can be in JSON format to update or push elements into arrays

Sub objects can be used with dot notation aka MySubObject.SubObjectVar will return status of UAPI_SUCCESS if operations was successful Only works on server

int Update(string oid, string element, string value, string operation = UpdateOpts.SET){}
int Update(string oid, string element, string value, string operation, Class cbInstance, string cbFunction){} //Return's Type UApiUpdateResponse

Update Call back function

protected void CBMyCallBackFunction(int cid, int status, string guid, UApiUpdateResponse data) {
   if ( status == UAPI_SUCCESS ){
      //Value Updated Successfully
   }
}

Queries

Queries allow you to search the database for you objects and return them in an array. Uses MongoDB Queries https://docs.mongodb.com/manual/tutorial/query-documents/

• Query Example "{ \"MyVar\": 3 }" would return all objects that have MyVar = 3
• Query Example "{ \"MyVar\": { \"$gte\": 5} }" would return all objects that have MyVar = 5 or higher
• Query Example "{ \"MyTStrringArray\": "somevalue" }" would return all objects that have a value of 'somevalue' inside the array
• Query Example "{ \"MySubObject.SubVar\": 3 }" would return all objects that have a SubVar = 3 inside a sub object this also works if the sub object was an array

• Only works on server for Player DB
• Works server and client on ObjectDB

int Query(UApiQueryBase query, Class cbInstance, string cbFunction){}
int Query(string query, Class cbInstance, string cbFunction){}

Call Back Function

protected void MyCallBackFunction(int cid, int status, string guid, UApiQueryResult<myClass> data) {
   if ( status == UAPI_SUCCESS ){
      //Do something with data
      array<autoptr myClass> results = data.GetResults();
   } else if (status == UAPI_EMPTY){ // no results
  }
}

Using the raw json api

Some basic documentation for the current Updated features.

//Client side is read only serverside for read and write
UApi().db(PLAYER_DB).   //Client Side reads to only their own GUID
UApi().db(OBJECT_DB).    //Client Side reads to all data

//Save data to the database
int Save(string mod, string oid, string jsonString, Class instance = NULL, string function = "")

//Can pass default in the jsonString to have the data set the data to that value if it doesn't exsit
int Load(string mod, string oid, Class instance, string function, string jsonString = "{}") 

// Mongo DB Queries including sub object array search is possible 
int Query(string mod, UApiQueryObject query, Class instance, string function)

// Dot Notation for elements aka to update something else you can do "something.somethingelse" as the element
//{ something: {
//    somethingelse: 1 }
//} 
int Transaction(string mod, string oid, string element, float value = 1, Class instance = NULL, string function = "")

int Update(string mod, string oid, string element, string value, string operation = "set", Class instance = NULL, string function = "")
//Valid update Opertation 
// `set` to set the value of an element
// `pull` to pull a value out of an array
// `push` to push a value into an array
// `pullAll` to empty an array
// `unset` to remove an element from the database
// `mul` to mulitply an element by the value in the database
// `rename` to rename an element in the database

Call Back Function

/* 
cid - is the call ID returned when the function request was called
status - returns the status of the call UAPI_SUCCESS, UAPI_EMPTY, UAPI_TIMEOUT, UAPI_CLIENTERROR, UAPI_SERVERERROR (for most call backs)
oid - is the Object ID or Player GUID of the requested player or object or in some cases the Id you specify if the request doesn't require an ID
data - is the data in a string format
*/
void CallbackFunction(int cid, int status, string oid, string data){
   if (status == UAPI_SUCCESS){
      YourClassName dataload;
      if (UApiJSONHandler<YourClassName>.FromString(data, dataload)){
         //Do you thing
      } else {
         Error("Failed to convert data to object");
      }
   } else if (status == UAPI_EMPTY) {
      //Response from API was empty meaning object does exist
   } else if (status == UAPI_TIMEOUT) {
      //Most likely the API is down
   } else if (status == UAPI_CLIENTERROR) {
      //Something was wrong with the request made
   } else if (status == UAPI_SERVERERROR) {
      // Something went wrong on the server side
   } else if (status == UAPI_NOTFOUND) {
      // Used with some discord call backs to signify user wasn't found or channel wasn't found
   } else if (status == UAPI_UNAUTHORIZED) {
      // not able to be implemented fully but shows that the client wasn't authenticated correctly
   }
}