Vp connect universe: Difference between revisions

From Virtual Paradise Wiki
Jump to navigation Jump to search
Roy Curtis (talk | contribs)
new page
Sleepy E (talk | contribs)
mNo edit summary
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{sdk method page|connect_universe|Connects an instance to a [[universe]] server. Required before an instance log in with user credentials and connects to any world.
{{Sdk method page|connect_universe|Connects an instance to a [[universe]] server. Required before an instance log in with user credentials and entering a world.
|paramex="universe.virtualparadise.org", 57000
|paramex="universe.virtualparadise.org", 57000
|parameters=
|parameters=
   {{sdk parameter row|string|host|Hostname of uniserver; typically {{code|"universe.virtualparadise.org"}}}}
   {{sdk parameter row|string|host|Host address of server to connect to; currently {{code|"universe.virtualparadise.org"}}. IP addresses in dotted quad are also valid (e.g. the string "10.0.0.1").}}
   {{sdk parameter row|int  |port|Port of uniserver; typically {{code|57000}}}}
   {{sdk parameter row|int  |port|TCP port of remote server; currently {{code|57000}}}}
|returncodes=
|returncodes=
  {{sdk return code row|NOT_INITIALIZED|SDK not initialized with {{sdk method|init}} yet}}
   {{sdk return code row|CONNECTION_ERROR|Error connecting to the universe server}}
   {{sdk return code row|CONNECTION_ERROR|Error connecting to the universe server}}
|caveats=To disconnect from a universe, {{sdk method|destroy}} must be called.
  {{sdk return code row|TIMEOUT        |It took too long to connect or get a response from the server}}
|behavior=
* If a {{sdk callback|connect_universe}} callback is set this function will return immediately and return the result using the callback, otherwise it will call {{sdk method|wait}} in a loop until done.
|caveats=
* To disconnect from a universe, {{sdk method|destroy}} must be called.
* Passing a NULL pointer for the host parameter will cause a memory access violation. It will not cause a default host address to be used. Passing port number 0 will also not cause a default port to be used.
* {{code|VP_RC_CONNECTION_ERROR}} could be returned for many issues, such as invalid host, unable to resolve IP address, wrong or invalid port, etc.
|examples=
|examples=
<C>
<syntaxhighlight lang="c">
int rc;
int rc;
if(rc = vp_connect_universe(instance, "universe.virtualparadise.org", 57000))
 
     printf("Error connecting to universe (reason %d)\n", rc);
rc = vp_connect_universe(instance, "universe.virtualparadise.org", 57000);
</C>
if (rc)
     printf("Couldn't connect to universe (reason %d)", rc);
</syntaxhighlight>
|seealso=
|seealso=
* [[vp_destroy]]
* {{sdk callback|CONNECT_UNIVERSE}}
* [[vp_login]]
* {{sdk method|destroy}}
* {{sdk method|login}}
}}
}}

Latest revision as of 20:16, 1 August 2018

Method call snippet vp_connect_universe(instance, "universe.virtualparadise.org", 57000);

Connects an instance to a universe server. Required before an instance log in with user credentials and entering a world.

Parameters

These are the parameters that this method requires:

Parameter Usage
VPInstance
instance
Pointer to the instance this method call is intended for
string
host
Host address of server to connect to; currently "universe.virtualparadise.org". IP addresses in dotted quad are also valid (e.g. the string "10.0.0.1").
int
port
TCP port of remote server; currently 57000

Returns

This method returns a return code integer, which indicates whether the call was successful or errored for any reason:

Return code Cause
VP_RC_SUCCESS Successful call (for methods that have a registered callback, it only means the request has been sent)
VP_RC_CONNECTION_ERROR Error connecting to the universe server
VP_RC_TIMEOUT It took too long to connect or get a response from the server

Behavior

  • If a VP_CALLBACK_CONNECT_UNIVERSE callback is set this function will return immediately and return the result using the callback, otherwise it will call vp_wait() in a loop until done.

Caveats

  • To disconnect from a universe, vp_destroy() must be called.
  • Passing a NULL pointer for the host parameter will cause a memory access violation. It will not cause a default host address to be used. Passing port number 0 will also not cause a default port to be used.
  • VP_RC_CONNECTION_ERROR could be returned for many issues, such as invalid host, unable to resolve IP address, wrong or invalid port, etc.

Examples

int rc;

rc = vp_connect_universe(instance, "universe.virtualparadise.org", 57000);
if (rc)
    printf("Couldn't connect to universe (reason %d)", rc);

See also