############################################################################## # # Copyright (c) 1998 - 2001 by # blaxxun interactive Inc, San Francisco, California, USA # All rights reserved # # MODULE NAME: $RCSfile: apextern.txt,v $ # REVISION: $Revision: 1.30 $ # DATE: $Date: 2001/02/16 12:46:20 $ # AUTHOR: $Author: peter $ # STATE: $State: Exp $ # # PROJECT: blaxxun # SYSTEM: server - blaxxun server processes - Community Server # SUBSYSTEM: doc - documentation of Community Server API # ############################################################################## # # Description of external interface of the Community Server API.Table of Contents:
The Community Server API allows third parties to extend the functionality
of blaxxun interactive's Community Platform.
By using this interface an application can control the Community Platform.
The following things can be controlled:
- Access to scenes by users.
- The attributes a user can use.
- The texts a user can send.
- Shared events.
Example applications that can be implemented based on the API server are:
- An autorisation server, that only allows users into a scene if they
know a correct password.
- A moderation server that only allows texts to be posted by specific
people.
- A vulgarity filter that suppresses texts using bad language.
- A shared event server that modifies shared events e.g. to control a game.
In order for an application process to access a Community Server,
the application process must be configured in the Community Server
configuration file via a
APISERVER statement.
The statement has the following form.
APISERVER <hostname>:<port>If the statement is given within a <SCENE> statement, the application can only control access for this specific scene.
where <hostname>:<port> is the hostname and port used by the application.
2.1. libchapi.a - UNIX library
contents
For UNIX systems
this library is distributed in directory src/linuxbin
and src/solarisbin.
The library contains the application interface. It is actually a blaxxun process
that has to be linked with the file apevent.o, libconfig.a, libpaa.a,
libpacket.a and libproc.a.
The interface to the process is as follows:
------------------------------------------------------------------------------
FUNCTION NAME: main apserver
DESCRIPTION:
Does the work of the API server.
The option -TRACE enables traces to the logfile.
This option can be toggled sending a kill -SIGUSR2 to the process.
The option -D prevents the process from disconnecting from the
control terminal for debug purposes.
IMPLICIT INPUTS:
The environment variable $BSIROOT has to be set.
The process assumes existence of the directories
$BSIROOT/log and $BSIROOT/status.
The other servers should get started as well.
IMPLICIT OUTPUTS:
Writes logs to the file $BSIROOT/log/apserver.<portnumberused>
RETURN VALUES:
The process can be terminated by kill -SIGTERM
exit( 0 ); OK
exit( 1 ); an error occured
DESIGN LANGUAGE:
None
------------------------------------------------------------------------------
*/
int main( int argc, char * argv[] )
{
static char usage[] =
"Usage: %s -p port [ application specific options ][ -TRACE -D ]\n\
where\n\
-p port: is the port the API server should work with\n\
-TRACE: enables the trace flag\n\
-D: is for debugging\n";
In order to use this process install Community Server 3.00, create the
apserver in src, copy it to the
Community Server <installdir>/bin directory
and add it to the file <installdir>/chstart.
For NT systems all binary files are distributed in directory src/ntbin
along with a MS VC++ 4.2 makefile.
In order to work properly with the Community Server admin interface, all
server processes need a name of the form xxserver. If you want to write
your own server you have to decide on a two letter prefix for your server
first.
Example: tfserver if you want to implement a text filtering server.
1. Edit file apntserv.h
- insert your own names for the both defines:
#define APNT_SERVICE_NAME "apserver"
// this is the name of your NT service and also the registry
// prefix for the "apserverPort" reg value.
#define APNT_REGVAL_IDSERVER "apserverIdserverHostPort"
// this is the name of the registry key for the idserver port
Edit the file apevent.c
- modify the existing event handler functions to your needs.
2. Open the makefile apserver.mak in VC++ 4.2.
Usage: sinstall.exe servicename servicedisplayname exepath
Example: sinstall.exe tfserver "Text Filter Process" c:\blaxxun\commserv\bin\tfserver.exe
5. Enter two new values in the registry:
- Open regedit.exe6. Start the NT Service Control Manager and start your new service. The new process writes a log file under <installdir>\log\
- Go to key HKEY_LOCAL_MACHINE/Software/blaxxunInteractive/Community Server
- Add a new String value "apserverPort" = 2070 (use the servicename you entered in the H-FILE for APNT_SERVICE_NAME as prefix, and choose an available UDP port)
- Add a new String value "apserverIdserverHostPort" = localhost:2000 (use the name you entered for APNT_REGVAL_IDSERVER for the reg value, and set the port of the idserver)
This include file gets distributed in directory src.
File apextern.h
PROJECT: VWP - blaxxun virtual worlds platform
SYSTEM: server - server processes
COMPONENT: apserver - Community Server API server
DESCRIPTION:
External include file for Community Server API server
This file contains all #defines and typedefs of the interface.
All event functions and API calls have function prototypes here.
This file resides in the directory src.
File apevent.c
PROJECT: VWP - blaxxun virtual worlds platform
SYSTEM: server - server processes
COMPONENT: apserver - Community Server API server
DESCRIPTION:
Event functions called. The functions given in this file are
examples for the Event Functions of the Interface.
Customize them to your own needs.
3.1. Makros and Constants
contents
*
* The following macros can be used to write logs or errors to stderr,
* if doing so the parameters have to be in printf format and two (( and ))
* have to be used
*
* Example:
*
* PROCESS_ERR(("malloc failed! errmsg: %s!\n", strerror( errno ) ));
*
*/
#ifndef PROCESS_LOG
#define PROCESS_LOG( X ) process_logout X
#endif
#ifndef PROCESS_ERR
#define PROCESS_ERR( X ) process_errout X
#endif
#ifndef PROCESS_TRA
#define PROCESS_TRA( X ) if( process.traceon ) process_traceout X
#endif
/* * Error return codes of the TCP/IP services library */ #define PACKET_ERR_SOCKET -1001 /* socket() call failed */ #define PACKET_ERR_BIND -1002 /* bind() call failed */ #define PACKET_ERR_HOST -1003 /* gethostbyname() call failed */ #define PACKET_ERR_MALLOC -1004 /* malloc() call failed */ #define PACKET_ERR_CONNECTION -1005 /* Invalid socket given as parameter */ #define PACKET_ERR_EINTR -1006 /* function interrupted by a signal */ #define PACKET_ERR_TIMEOUT -1007 /* Timeout waiting with select */ #define PACKET_ERR_SELECT -1008 /* Error waiting with select */ #define PACKET_ERR_RECV -1009 /* Network read error in receive call */ #define PACKET_ERR_LISTEN -1010 /* listen() call failed */ #define PACKET_ERR_ACCEPT -1011 /* accept() call failed */ #define PACKET_ERR_EWOULDBLOCK -1012 /* operation (send,recv) would block */ #define PACKET_ERR_CONNECT -1013 /* connect() call failed */ #define PACKET_ERR_SEND -1014 /* send() call failed */ #define PACKET_ERR_INVAL -1015 /* invalid argument */
*/ /* * Defines for events that are usable, used in function chSessionRegisterEvent. */ #define apchEventUserNew 1 #define apchEventUserNewLog 2 #define apchEventUserDelete 3 #define apchEventUserSetAttr 4 #define apchEventUserSetAttrLog 5 #define apchEventUserText 6 #define apchEventUserTextLog 7 #define apchEventSceneNew 8 #define apchEventSceneDelete 9 #define apchEventUdpRequest 10 #define apchEventHttpRequest 11 #define apchEventUserPosition 12 #define apchEventUserPositionLog 13 /* * Defines for reasons why a user is denied * Used in event function chEventUserNew and function chUserSetDenied * and in event function chEventUserSetAttr and function chUserSetNewDataFailed. */ #define CH_AUTHORISATIONFAILURE 6 #define CH_BADVERSION 8 #define CH_BADSCENE 9 #define CH_NEEDAUTHORISATION 10 #define CH_BADURL 11 #define CH_NOMORE 12 #define CH_BADNICKNAME 15 #define CH_BADINFO 16 #define CH_BADATTR 17 /* * Defines for codes of attributes for event functions * chEventUserSetAttr and chEventUserSetAttrLog */ #define CH_URL_TYPE 2 #define CH_NICKNAME_TYPE 3 #define CH_INFO_TYPE 10 #define CH_ATTR_TYPE 30 /* * Defines for shared event types */ #define APSE_SFBOOL 1 #define APSE_SFIMAGE 2 #define APSE_SFTIME 3 #define APSE_SFCOLOR 4 #define APSE_MFCOLOR 5 #define APSE_SFFLOAT 6 #define APSE_MFFLOAT 7 #define APSE_SFINT32 8 #define APSE_MFINT32 9 #define APSE_SFNODE 10 #define APSE_MFNODE 11 #define APSE_SFROTATION 12 #define APSE_MFROTATION 13 #define APSE_SFSTRING 14 #define APSE_MFSTRING 15 #define APSE_SFVEC2F 16 #define APSE_MFVEC2F 17 #define APSE_SFVEC3F 18 #define APSE_MFVEC3F 19 #define APSE_SFENUM 20 #define APSE_SFBITMASK 21 #define APSE_SFMATRIX 22 #define APSE_SFLONG 23 #define APSE_MFLONG 24 /* * membertypes */ #define CHDB_IS_BAD 0 #define CHDB_IS_VISITOR 1 #define CHDB_IS_MEMBER 2 #define CHDB_IS_ADMIN 3 /* * Access bits for rights_check */ #define CHDB_ACCESS_READ 0x4 /* read access */ #define CHDB_ACCESS_WRITE 0x2 /* write access */ #define CHDB_ACCESS_OWN 0x1 /* owner access */ #define CHDB_ACCESS_RCHANGE 0x8 /* rights change */ #define CHDB_ACCESS_ALL 0x7 /* rwo bits */ #define CHDB_ACCESS_ALLBITS 0xf /* all bits */ /* * datatype/table names for member and chat places */ #define CHDB_MEMBER_TYPE "M" /* member table */ #define CHDB_MEMBERDATA_TYPE "MD" /* member data table */ #define CHDB_MEMBERONLINE_TYPE "MO" /* member online table */ #define CHDB_VISITOR_TYPE "VI" /* visitor table */ #define CHDB_OBJECT_TYPE "O" /* places table */ #define CHDB_HOME_TYPE "H" /* homesteading table */ #define CHDB_COMM_TYPE "C" /* old community table */ #define CHDB_NEIGH_TYPE "N" /* old neighbor table */ #define CHDB_BLOCK_TYPE "B" /* old block table */ #define CHDB_PROP_TYPE "P" /* old property table */ #define CHDB_CLUB_TYPE "CL" /* club table */ /* * attribute names */ #define CHDB_ATTR_ID "ID" /* id keytype */ #define CHDB_ATTR_NNM "NNM" /* nickname keytype */ /* * db specific error codes */ #define CHDB_ERR_DUPKEY -101 /* unique secodary key already exists */ #define CHDB_ERR_KEYNOTFOUND -102 /* key not found during update */ /* * A makro that determines whether the end of an iterator list * is reached, use it with the Handle returned by chSessionGetNext * and chUserGetNext. */ #define CHEoList( H ) (( H.sessionid == -1 ) && ( H.clientid == -1 ))
*
*/
/*
* The eventTag passed to the EventRegister function
*/
typedef int CHEvent_t;
/*
* A generic 4 byte value
*/
typedef unsigned long CH_4byte_t;
/*
* A generic 2 byte value
*/
typedef unsigned short CH_2byte_t;
/*
* An IP address, always used in network byte order
*/
typedef unsigned long CH_ip_t;
/*
* A port number, always used in network byte order
*/
typedef unsigned short CH_port_t;
/*
* A protocol version as used by the clients
*/
typedef unsigned long CH_version_t;
/*
* A Community Server ID
*/
typedef CH_4byte_t CH_id_t;
/*
* A Client install ID as sent by the client
*/
typedef struct
{
CH_4byte_t installid1;
CH_4byte_t installid2;
} CHInstallId_t;
/*
* A Handle as we pass it to event functions
*/
typedef struct
{
CH_id_t sessionid;
CH_id_t clientid;
CH_port_t port;
CH_ip_t ip;
} CHHandle_t;
/*
* A position as stored in memory
*/
typedef struct
{
long x;
long y;
long z;
} CHPosition_t; /* an x-y-z position */
/*
* An orientation as stored in memory
*/
typedef struct
{
int x; /* x component of unit vector */
int y; /* y component of unit vector */
int z; /* z component of unit vector */
unsigned int a; /* the angle */
} CHOrientation_t; /* an orientation */
/*
* A pointer to an event function
*/
typedef void (* CHHandlerFuncPtr_t) ( CHHandle_t handle, int code );
/*
* The following type is used internally by the API server
*/
typedef struct apserver_s
{
time_t now; /* the current time set by ap_reply */
CH_port_t port; /* port number used by API server */
CH_ip_t ip; /* ip address used by server */
int socket; /* socket used by API server */
time_t lastlog; /* last time log was printed */
volatile int statusprint; /* flag for status print, set by */
/* id_sigusr1_handler */
void * iter; /* current iterator element */
char * sessionpaa; /* hash table for known sessions */
void * sessionhead; /* head of list of session we know */
void * sessiontail; /* tail of list of sesions we know */
char * clientpaa; /* hash table for known clients */
/* number of packets received of type */
unsigned long tusers;
unsigned long nusers;
unsigned long tscenes;
unsigned long nscenes;
unsigned long tsessions;
unsigned long nsessions;
unsigned long tevents;
unsigned long tapchEventPeriodic;
unsigned long tapchEventUserPacket;
unsigned long tapchEventSessionReqSubscribe;
unsigned long tapchEventSessionAckSubscribe;
unsigned long tapchEventUserNew;
unsigned long tapchEventUserNewLog;
unsigned long tapchEventUserDelete;
unsigned long tapchEventUserSetAttr;
unsigned long tapchEventUserSetAttrLog;
unsigned long tapchEventUserText;
unsigned long tapchEventUserTextLog;
unsigned long tapchEventUserPositionLog;
unsigned long tapchEventSceneNew;
unsigned long tapchEventSceneDelete;
/*
* packets received
*/
unsigned long nAPDataPacketsReceived;
unsigned long nAPDataReplaysReceived;
unsigned long n0packets; /* length 0 */
unsigned long nunknown;
unsigned long nreqsubscribe;
unsigned long nacksubscribe;
unsigned long nconfsubscribe;
unsigned long nlog;
unsigned long nquery;
unsigned long ngetid;
unsigned long nscenecreate;
unsigned long nscenedelete;
unsigned long ncupd;
unsigned long nsetx;
unsigned long nsetattr;
unsigned long ntextsend;
unsigned long ntextgrsend;
unsigned long nuserdata;
unsigned long ncommandfailed;
/*
* packets sent
*/
unsigned long nInitsubscribe;
unsigned long nCmdsubscribe;
unsigned long nAck;
unsigned long nFail;
unsigned long nHandle;
unsigned long nClientpacket;
struct timeval period;
int (*usrdata_handler)(); /* Pointer to handler for unknown packets */
int sessionAllowAll; /* allow sessions from any community server */
int useSEServer; /* activate the SE server */
int useSOServer; /* run an soserver, do the license check */
} apserver_t;
Unconditional Event Functions are called by the Community Server API
regardless of whether they are registered as events or not.
Examples for the functions are supplied in apevent.c. Those functions
may be customized by users of the API server.
4.1. chEventStartup
contents
------------------------------------------------------------------------------
FUNCTION NAME: chEventStartup
DESCRIPTION:
This function is called when the API server is started.
The code given as an example here creates a session to each Community Server
given on the command line as:
-i hostname:port
If the option
-i all
is given the example code allows sessions from any Community Server
sending a request subcribe.
Add your own code as you like, but make sure to create at least one
session or to allow sessions from any hosts.
NOTE: In order to make the process run correctly on NT this function must
not perform any exits, use a return code of 110 or higher as the
example does.
RETURN VALUES:
int rc == 0: ok process started successfully
rc != 0: the startup failed, the process will go down with
the exitcode returned
------------------------------------------------------------------------------
*/
int chEventStartup(
int argc, /* number of parameters */
char *argv[] /* comamnd line parameters */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventShutdown
DESCRIPTION:
This function is called when the API server is terminated.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventShutdown(
int exitcode /* return code for exit call */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventSessionReqSubscribe
DESCRIPTION:
This function is called when Community Server requests the API server to
subscribe to certain events.
This can either happen:
- at startup time of the API server
- in case Community Server is restarted.
See apextern.h for a list of possible events this function can
subscribe to.
The code here subscribes to all events that are possible.
The parameter "unknown" has the following meaning.
unknown == 0: The Community Server requesting the session request subscribe
has been explicitly created by this application via a
call to chSessionCreate.
unknown != 0: The Community Server requesting the session request subscribe
has not been explictly created by this application.
In this case the function can decide whether it wants
to subscribe to the Community Server in question.
It can either accept the session by calling chSessionAllow
and then registering to certain events with the
Community Server. Or it can ignore the session with
the Community Server by doing nothing.
The case unknown != 0 will only happen if sessions by unknown Community
Servers were enabled during startup by a call to chSessionAllowAll.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventSessionReqSubscribe(
CHHandle_t sessionHandle, /* r: handle for session structure */
int sessionUnknown /* r: flag: session is explicit */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventSessionAckSubscribe
DESCRIPTION:
This function is called when Community Server acknowledges the subscription
for a session.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventSessionAckSubscribe(
CHHandle_t sessionHandle, /* r: handle for session structure */
int code /* r: unused in this function */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventSessionPeriodic
DESCRIPTION:
This function is called periodically for each session existing.
The default is every 60 seconds, the default can be changed by
calling chSessionSetPeriod.
The minimum value possible for period is 100000 microseconds.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventSessionPeriodic(
CHHandle_t sessionHandle /* r: handle for session structure */
)
All User Related Event Functions have to be registered with
the Community Server Api before they are called.
Examples for the functions are supplied in apevent.c. Those functions
may be customized by users of the API server.
5.1. chEventUserNew
contents
------------------------------------------------------------------------------
FUNCTION NAME: chEventUserNew
DESCRIPTION:
Event function for a new user event.
This function is called whenever a client tries to enter a specific scene
with Community Server.
This is an example function, it is only called when the event
apchEventUserNew is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The function can read the values used by the client by calls to the
chUserGet... functions.
The function can change the values used by a client by calls to the
chUserSet... functions. The client will not be told about this
change of values. This is useful for example in order to make
the client use a different avatar without further ado.
The function can deny a client by calling the chUserSetDenied function.
Reason codes for the deny are specified in apextern.h.
The function can let the client enter the scene as specified by
doing nothing.
Beware: This call is blocking, Community Server will only allow the client
to enter the scene specified after this function returns.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUserNew(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: unused in this function */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventUserNewLog
DESCRIPTION:
Event function for a EventUserNewLog event
This function is called whenever a client has entered a specific scene
with Community Server.
This is an example function, it is only called when the event
apchEventUserNewLog is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The function can read the values used by the client by calls to the
chUserGet... functions.
Community Server has already allowed the client to enter the scene when the
function is called.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUserNewLog(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: unused in this function */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventUserDelete
DESCRIPTION:
Event function for a Delete user event
This function is called whenever a client leaves a scene at Community Server.
This is an example function, it is only called when the event
apchEventUserDelete is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The client has already left the scene specified when this function is called.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUserDelete(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: unused in this function */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventUserSetAttr
DESCRIPTION:
Event function for a chEventUserSetAttr event
This function is called whenever a client changes one of its attributes.
This is an example function, it is only called when the event
chEventUserSetAttr is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The attributes that can be changed by a client are the url of its avatar,
its nickname, its public info and its application attributes.
In particular if ( attr & 1 ) is true for the application attributes,
the client is invisible to other clients in the scene.
The function can deny the change of attributes by calling the
chUserSetNewDataFailed function.
Reason codes for the deny are specified in apextern.h.
The function can allow the change of attributes by calling the
chUserSetNewData function.
The function can silently ignore the change of attributes by doing
nothing. The client will not be told about this denial of
change of values. This is useful for example in order to make
the client not use a different avatar without further ado.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUserSetAttr(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: code which attribute changed */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventUserSetAttrLog
DESCRIPTION:
Event function for a apchEventUserSetAttrLog event
This function is called whenever a client changes one of its attributes.
This is an example function, it is only called when the event
apchEventUserSetAttrLog is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The function can read the new attributes.
The new attributes are already accepted by Community Server when this function
is called.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUserSetAttrLog(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: code which attribute changed */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventUserText
DESCRIPTION:
Event function for a chEventUserText event
This function is called whenever a client sends a text.
The function can read the text sent by calling the
chUserGetText function.
The function can find out the group id of the text group the text
was sent to by calling the chUserGetGroupID function.
The function can find out the topic of the text group the text
was sent to by calling the chUserGetGroupTopic function.
The function can ignore the sending of the text by calling the
chUserSetTextIgnore function. The text will not be forwarded to
any other users in this case.
The function can replace the text sent by the user with a replacement
text by calling the chUserSetText function.
The client will not be told that the text was ignored or changed.
This is an example function, it is only called when the event
chEventUserText is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUserText(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: unused in this function */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventUserTextLog
DESCRIPTION:
Event function for a apchEventUserTextLog event
This function is called whenever a client sends a text.
This is an example function, it is only called when the event
apchEventUserTextLog is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The function can read the text sent, by calling chUserGetText.
The function can find out the group id of the text group the text
was sent to by calling the chUserGetGroupID function.
The function can find out the topic of the text group the text
was sent to by calling the chUserGetGroupTopic function.
The text has already been forwarded to the other clients when this
function is called.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUserTextLog(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: unused in this function */
)
All Scene Related Event Functions have to be registered with
the Community Server Api before they are called.
Examples for the functions are supplied in apevent.c. Those functions
may be customized by users of the API server.
6.1. chEventSceneNew
contents
------------------------------------------------------------------------------
FUNCTION NAME: chEventSceneNew
DESCRIPTION:
Event function for a EventSceneNew event
This function is called whenever a new scene gets created by
Community Server.
This is an example function, it is only called when the event
apchEventSceneNew is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The function can read the values set for the scene by using the
chSceneGet... functions.
Community Server has already created the scene when the function is called.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventSceneNew(
CHHandle_t sceneHandle, /* r: handle for scene structure */
int code /* r: unused in this function */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventSceneDelete
DESCRIPTION:
Event function for a EventSceneDelete event
This function is called whenever a scene gets deleted by
Community Server.
This is an example function, it is only called when the event
apchEventSceneDelete is registered via a call to chSessionRegisterEvent
and chSessionCmdSubscribe.
The function can read the values set for the scene by using the
chSceneGet... functions.
Community Server has already deleted the scene when the function is called.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventSceneDelete(
CHHandle_t sceneHandle, /* r: handle for scene structure */
int code /* r: unused in this function */
)
The following API Calls exist for Session Objects.
7.1. Creation, Subscribe, Register Events, Access
contents
7.1.1. chSessionAllowAll
contents
------------------------------------------------------------------------------
FUNCTION NAME: chSessionAllowAll
DESCRIPTION:
This sets a flag with the API server telling it to accept
connections from any Community Server regardless of whether
a session was created beforehand via a call to chSessionCreate.
The default of the flag at startup time of the API server is 0.
I.e. only sessions from community servers explicitly created
via a call to chSessionCreate are allowed.
If this flag is set, request subscribe requests from unknown
Community Servers will result in a call to chEventSessionReqSubscribe
with parameter "unknown" set to 1.
See chEventSessionReqSubscribe for how to handle such subcribe requests.
RETURN VALUES:
int rc: The previous value of the SessionAllowAll flag of the API server.
------------------------------------------------------------------------------
*/
int chSessionAllowAll(
int allow /* flag: Allow sessions from any Community Server */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionAllow
DESCRIPTION:
This function tells the API server to allow a session by a Community
Server. It has to be called in the event function
chEventSessionReqSubscribe in order to allow a session from
a Community Server that was not explicitly created by a call to
chSessionCreate.
If chEventSessionReqSubscribe is called with parameter
unknown != 0
and this function is not called subsequently, the session by the
unknown Community Server is ignored.
RETURN VALUES:
int rc == 0: Call went ok.
int rc == -1: sessionHandle is invalid
------------------------------------------------------------------------------
*/
int chSessionAllow(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionCreate
DESCRIPTION:
Create a session for the API server.
After creation of a session, the Community Server in question will be
continously informed about the existence of the API server.
If the API server is configured with Community Server, Community Server
will answer with a request to subscribe.
This will cause the chEventSessionReqSubscribe function to be called.
Furthermore the chEventSessionPeriodic event function will be called
periodically for the session.
If you want to do timeout handling in case Community Server does not answer,
use the results of the functions chSessionGetCreateTime and
chSessionGetReqSubscribeTime for determining the time elapsed since
creation of the session.
RETURN VALUES:
int rc == 0: Session create went ok
int rc == -1: Out of memory
int rc == -2: There is already a session to the Community Server with internet
address and port specified.
------------------------------------------------------------------------------
*/
int chSessionCreate(
char * hostname, /* r: name of host of ID server */
CH_port_t port, /* r: port used by ID server */
char * addr, /* r: internet address of ID server */
int alen /* r: length of that address */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionCmdSubscribe
DESCRIPTION:
This subscribes the events set by previous calls to chSessionRegisterEvent
with Community Server.
This registers the events registered locally with Community Server.
If Community Server acknowledges the registration the
chEventSessionAckSubscribe function will be called.
RETURN VALUES:
int rc == 0: ok, subscribe sent
int rc == -1: sessionHandle is invalid
------------------------------------------------------------------------------
*/
int chSessionCmdSubscribe(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionRegisterEvent
DESCRIPTION:
Register an event funktion for one of the events.
See apextern.h for events that can be registered.
If the eventFunc is NULL, the event is disabled.
RETURN VALUES:
int rc == 0: ok, event registered
int rc == -1: sessionHandle is invalid
int rc == -2: eventTag is invalid
------------------------------------------------------------------------------
*/
int chSessionRegisterEvent(
CHHandle_t sessionHandle, /* r: handle for session structure */
CHEvent_t eventTag, /* r: which event to register */
CHHandlerFuncPtr_t eventFunc /* r: function that handles event */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionResetIter
DESCRIPTION:
Resets the list iterator of the session list to top of the list. Call
csSessionGetNext() to retrieve all session objects.
RETURN VALUES:
int rc == -1: There is no session at all
------------------------------------------------------------------------------
*/
int chSessionResetIter( void )
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetNext
DESCRIPTION:
The session list iterator advances to the next list entry.
RETURN VALUES:
CHHandle_t Handle: Use the makro CHEoList on the handle returned.
CHEoList( Handle ) != 0: The End of the list has been reached.
CHEoList( Handle ) == 0: Handle is the Handle of the next element of the list.
------------------------------------------------------------------------------
*/
CHHandle_t chSessionGetNext( void )
7.2.1. chSessionSetPeriod
contents
------------------------------------------------------------------------------
FUNCTION NAME: chSessionSetPeriod
DESCRIPTION:
Sets the period in which the periodic event of a session is called.
RETURN VALUES:
int rc == 0: The period was set
int rc == -1: The sessionHandle is invalid
------------------------------------------------------------------------------
*/
int chSessionSetPeriod(
CHHandle_t sessionHandle, /* r: handle for session structure */
struct timeval period /* r: period to be used for the session */
)
7.3.1. chSessionGetAckSubscribeTime
contents
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetAckSubscribeTime
DESCRIPTION:
Gets the time in seconds since the epoch,
since when the last ackSubscribe event was received.
RETURN VALUES:
time_t rc == -1: The sessionHandle is invalid
time_t rc == 0: There was never a ackSubscribe received
otherwise: The time when the last ackSubscribe arrived.
------------------------------------------------------------------------------
*/
time_t chSessionGetAckSubscribeTime(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetApiId
DESCRIPTION:
Gets the API Id of the session in question.
RETURN VALUES:
CH_id_t rc == 0: The sessionHandle is invalid
otherwise: The API ID of the session in question.
------------------------------------------------------------------------------
*/
CH_id_t chSessionGetApiId(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetCreateTime
DESCRIPTION:
Gets the time in seconds since the epoch when the session was created.
RETURN VALUES:
time_t rc == -1: The sessionHandle is invalid
time_t rc == 0: The session was never created
otherwise: The time when the session was created.
------------------------------------------------------------------------------
*/
time_t chSessionGetCreateTime(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetIdserverHostname
DESCRIPTION:
Gets the Hostname used by the ID server of a session
RETURN VALUES:
char * retptr == NULL: The sessionHandle is invalid
otherwise: The Hostname of the ID server of the session.
A \0 terminated string.
------------------------------------------------------------------------------
*/
char * chSessionGetIdserverHostname(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetIdserverIP
DESCRIPTION:
Gets the IP address used by the ID server of the Community Server
connected to a session.
RETURN VALUES:
CH_ip_t rc == 0: The sessionHandle is invalid
otherwise: The IP address of the ID server of the session in
network byte order.
------------------------------------------------------------------------------
*/
CH_ip_t chSessionGetIdserverIP(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetIdserverPort
DESCRIPTION:
Gets the Port number used by the ID server of a session.
RETURN VALUES:
CH_port_t rc == 0: The sessionHandle is invalid
otherwise: The Port number of the ID server of the session in
network byte order.
------------------------------------------------------------------------------
*/
CH_port_t chSessionGetIdserverPort(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetLastPacketTime
DESCRIPTION:
Gets the time in seconds since the epoch,
since when the last packet was received for the session.
RETURN VALUES:
time_t rc == -1: The sessionHandle is invalid
time_t rc == 0: There was never a packet received
otherwise: The time when the last packet arrived.
------------------------------------------------------------------------------
*/
time_t chSessionGetLastPacketTime(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetNofScenes
DESCRIPTION:
Gets the number of scenes active in a session
RETURN VALUES:
int rc < 0: The sessionHandle is invalid
otherwise: number of scenes in the session
------------------------------------------------------------------------------
*/
int chSessionGetNofScenes(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetPort
DESCRIPTION:
Gets the Port number used by a session
RETURN VALUES:
CH_port_t rc == 0: The sessionHandle is invalid
otherwise: The port number used by the session in network byte order.
------------------------------------------------------------------------------
*/
CH_port_t chSessionGetPort(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetReqSubscribeTime
DESCRIPTION:
Gets the time in seconds since the epoch,
since when the last reqSubscribe event was received.
RETURN VALUES:
time_t rc == -1: The sessionHandle is invalid
time_t rc == 0: There was never a reqSubscribe received
otherwise: The time when the last reqSubscribe arrived.
------------------------------------------------------------------------------
*/
time_t chSessionGetReqSubscribeTime(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSessionGetSocket
DESCRIPTION:
Gets the socket fd that is used by a session
RETURN VALUES:
int rc == -1: The sessionHandle is invalid
int rc == -2: The session does not have a socket
otherwise: The socket used by the session
------------------------------------------------------------------------------
*/
int chSessionGetSocket(
CHHandle_t sessionHandle /* r: handle for session structure */
)
The following API Calls exist for User Objects.
8.1. Accesssing Existing Users per Session and per Scene
contents
8.1.1. chUserResetIter
contents
------------------------------------------------------------------------------
FUNCTION NAME: chUserResetIter
DESCRIPTION:
Resets the list iterator of the user list of a session to top of the list.
Call chUserGetNext() to retrieve all user objects.
RETURN VALUES:
int rc == -1: There is no user at all
int rc == -2: The session handle used is invalid
------------------------------------------------------------------------------
*/
int chUserResetIter(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetNext
DESCRIPTION:
The user list iterator advances to the next list entry.
RETURN VALUES:
CHHandle_t Handle: Use the makro CHEoList on the userHandle returned.
CHEoList( Handle ) != 0: The End of the list has been reached.
CHEoList( Handle ) == 0: Handle is the userHandle of the next
element of the list.
------------------------------------------------------------------------------
*/
CHHandle_t chUserGetNext(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneUserResetIter
DESCRIPTION:
Resets the list iterator of the user list of a scene to top of the list.
Call chSceneUserGetNext() to retrieve all user objects.
RETURN VALUES:
int rc == -1: There is no user at all
int rc == -2: The scene handle used is invalid
------------------------------------------------------------------------------
*/
int chSceneUserResetIter(
CHHandle_t sceneHandle /* r: handle for scene structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneUserGetNext
DESCRIPTION:
The user list per scene iterator advances to the next list entry.
RETURN VALUES:
CHHandle_t Handle: Use the makro CHEoList on the userHandle returned.
CHEoList( Handle ) != 0: The End of the list has been reached.
CHEoList( Handle ) == 0: Handle is the userHandle of the next
element of the list.
------------------------------------------------------------------------------
*/
CHHandle_t chSceneUserGetNext(
CHHandle_t sceneHandle /* r: handle for scene structure */
)
8.2.1. chUserSendText
contents
------------------------------------------------------------------------------
FUNCTION NAME: chUserSendText
DESCRIPTION:
Sends a text as a user.
If the pointer to the receiverHandle is not NULL the text is only sent
to that specific user.
Otherwise the text is sent to all members of of the group specified
but not to the sending user.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The text can't be sent
int rc == -3: The receiver handle is not NULL and does not specify an
existing user.
------------------------------------------------------------------------------
*/
int chUserSendText(
CHHandle_t userHandle, /* r: handle for user structure */
CHHandle_t *receiverHandle, /* r: handle for receiving user */
const char* text, /* r: text to set */
int textlen, /* r: length of that text */
const char* topic, /* r: topic of group to send to */
int topiclen /* r: length of that topic */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetAttr
DESCRIPTION:
Sets the application attributes for the user, this function can only be used
from inside a chEventUserNew handler function.
This function can be used to change the application attributes
used by a user entering a scene.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserNew
Event handler function
int rc == -3: The length of the application attributes to set is not
sizeof( CH_4byte_t ).
------------------------------------------------------------------------------
*/
int chUserSetAttr(
CHHandle_t userHandle, /* r: handle for user structure */
CH_4byte_t attr, /* r: attr to set */
int attrlen /* r: length of that attr */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetDenied
DESCRIPTION:
Sets the denied flag for the user, this function can only be used
from inside a chEventUserNew handler function.
Unless th reason is CH_NOMORE to remove a user from the scene afterwards.
This is used by the msserver for excluded users.
The user will not be allowed to enter the scene with Community Server, the
reason given here will be sent to the user.
See apextern.h for reason codes.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserNew
Event handler function
------------------------------------------------------------------------------
*/
int chUserSetDenied(
CHHandle_t userHandle, /* r: handle for user structure */
int reasonCode /* r: reasoncode for user deny */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetInfo
DESCRIPTION:
Sets the info for the user, this function can only be used
from inside a chEventUserNew handler function.
This function can be used to change the info of a user entering a
scene.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserNew
Event handler function
------------------------------------------------------------------------------
*/
int chUserSetInfo(
CHHandle_t userHandle, /* r: handle for user structure */
const char* info, /* r: info to set */
int infolen /* r: length of that info */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetNewData
DESCRIPTION:
Sets the value of the new data a user wants to set.
This function can only be called from within a
apchEventUserSetAttr event handling function
If this function is called from within the apchEventUserSetAttr
event handling function the change of attributes requested by the
user will be confirmed.
RETURN VALUES:
int rc == 0: The new data has been set
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserSetAttr
Event handler function
int rc == -3: code is invalid
------------------------------------------------------------------------------
*/
int chUserSetNewData(
CHHandle_t userHandle, /* r: handle for user structure */
int code /* r: the code of the data to set */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetNewDataFailed
DESCRIPTION:
This function can only be called from inside the apchEventUserSetAttr
Event Handler function.
Use it to inform the user that his attempt to change one of the attributes
was denied. Give the reason for the deny.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserNew
Event handler function
------------------------------------------------------------------------------
*/
int chUserSetNewDataFailed(
CHHandle_t userHandle, /* r: handle for user structure */
int reasonCode /* r: reasoncode for user deny */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetNickname
DESCRIPTION:
Sets the nickname for the user, this function can only be used
from inside a chEventUserNew handler function.
This function can be used to change the nickname
used by a user entering a scene.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserNew
Event handler function
------------------------------------------------------------------------------
*/
int chUserSetNickname(
CHHandle_t userHandle, /* r: handle for user structure */
const char* nickname, /* r: nickname to set */
int nicknamelen /* r: length of that nickname */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetText
DESCRIPTION:
Sets a replacement text for a text sent by a user.
The replacement text will be sent to the peers of the
user instead of the text the user sent.
This function can only be used from inside a chEventUserText
handler function.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserText
Event handler function
------------------------------------------------------------------------------
*/
int chUserSetText(
CHHandle_t userHandle, /* r: handle for user structure */
const char* text, /* r: text to set */
int textlen /* r: length of that text */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetTextIgnore
DESCRIPTION:
Sets the ignore flag for the last text the user sent.
this function can only be used from inside a chEventUserText
handler function.
The text the user has sent will not be forwarded to the peers.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserText
Event handler function
------------------------------------------------------------------------------
*/
int chUserSetTextIgnore(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetUrl
DESCRIPTION:
Sets the url for the user, this function can only be used
from inside a chEventUserNew handler function.
This function can be used to change the url of the avatar
used by a user entering a scene.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
int rc == -2: The function was called from outside the apchEventUserNew
Event handler function
------------------------------------------------------------------------------
*/
int chUserSetUrl(
CHHandle_t userHandle, /* r: handle for user structure */
const char* url, /* r: url to set */
int urllen /* r: length of that url */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserSetApplicationData
DESCRIPTION:
Sets the application data for the user.
The application can read the data it has set for a user by a call to
chUserGetApplicationData.
This function does not malloc or free any data buffers,
nor does it do any consistency checks on the application data,
it simply lets the application set a pointer and an integer value
that can be retrieved later.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The userHandle is invalid
------------------------------------------------------------------------------
*/
int chUserSetApplicationData(
CHHandle_t userHandle, /* r: handle for user structure */
char *data, /* r: data to set */
int datalen /* r: length of that data */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetAttr
DESCRIPTION:
Gets the value of the application attributes of a user.
The application attributes are actually of type CH_4byte_t.
Use memcpy to copy the data into a variable of that type before
you use it.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetAttr(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetCreateTime
DESCRIPTION:
Gets the time in seconds since the epoch when the user was created.
RETURN VALUES:
time_t rc == -1: The userHandle is invalid
otherwise: The time when the user was created.
------------------------------------------------------------------------------
*/
time_t chUserGetCreateTime(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetLastTextTime
DESCRIPTION:
Gets the time in seconds since the epoch when the user sent the last
text.
If this function is called during a chEventUserText or chEventUserTextLog
event it returns the time the last text was sent by the user, not the
current time.
RETURN VALUES:
time_t rc == -1: The userHandle is invalid
otherwise: The time when the user sent the last text.
------------------------------------------------------------------------------
*/
time_t chUserGetLastTextTime(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetDenied
DESCRIPTION:
Gets the value of the Denied status of a user.
This is the value set by chUserSetDenied during handling of
chEventUserNew.
RETURN VALUES:
int rc == -1: The userHandle is invalid.
int rc == 0: The user was allowed in the scene.
otherwise: The user was not allowed in the scene. The reason set for
the deny is returned.
------------------------------------------------------------------------------
*/
int chUserGetDenied(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetEncryption
DESCRIPTION:
Gets the value of the Encryption of the passwd used by a user.
The encryption is currently unused in the protocol.
RETURN VALUES:
int rc == -1: The userHandle is invalid.
otherwise: The encryption used for the passwd of the user.
No values are defined up to now.
------------------------------------------------------------------------------
*/
int chUserGetEncryption(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetGroupID
DESCRIPTION:
Gets the ID of the group a text was sent to.
This function can only be called from within a
apchEventUserText or apchEventUserTextLog event handling
function
RETURN VALUES:
CH_id_t rc == -1: The userHandle is invalid
CH_id_t rc == 0: The last text was not sent to a specific group.
otherwise: otherwise the group id
------------------------------------------------------------------------------
*/
CH_id_t chUserGetGroupID(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetGroupTopic
DESCRIPTION:
Gets the value of the topic of the group a text was sent to.
This function can only be called from within a
apchEventUserText or apchEventUserTextLog event handling
function
It returns the topic of the group the user wants to send text to.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetGroupTopic(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetId
DESCRIPTION:
Gets the value of the ID used by a user.
RETURN VALUES:
CH_id_t rc == 0: The userHandle is invalid
otherwise: the ID of the user
------------------------------------------------------------------------------
*/
CH_id_t chUserGetId(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetInfo
DESCRIPTION:
Gets the value of the public info of a user.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetInfo(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetInstallId
DESCRIPTION:
Gets the value InstallId of the client installation of the user
CyberGate up to Beta 5 sends always 0,0.
CyberHubClient and Passport send an 8 byte ID unique for each installation.
RETURN VALUES:
CHInstallId_t rc == -1: The userHandle is invalid.
otherwise: The value set by the user.
------------------------------------------------------------------------------
*/
CHInstallId_t chUserGetInstallId(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetIp
DESCRIPTION:
Gets the value of the IP address of the machine used by a user.
If the user uses a TCP proxy connection, this call will return
the address of the machine the Community Server Proxy server
runs on.
RETURN VALUES:
CH_ip_t rc == 0: The userHandle is invalid
otherwise: the IP address of the machine the user is on in network
byte order
------------------------------------------------------------------------------
*/
CH_ip_t chUserGetIp(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetRealIp
DESCRIPTION:
Gets the value of the IP address of the machine used by a user.
If the user uses a TCP proxy connection, this call will return
the address of the machine the client runs on.
RETURN VALUES:
CH_ip_t rc == 0: The userHandle is invalid
otherwise: the IP address of the machine the user is on in network
byte order
------------------------------------------------------------------------------
*/
CH_ip_t chUserGetRealIp(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetSceneName
DESCRIPTION:
Gets the value of the logical scene name the user has set for the scene
it is in.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetSceneName(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetSceneHandle
DESCRIPTION:
Gets the scene handle of the scene the user is in.
This scene handle can be used in subsequent chSceneGet...
functions.
RETURN VALUES:
CHHandle_t Handle: Use the makro CHEoList on the sceneHandle returned.
CHEoList( Handle ) != 0: The userHandle specified is invalid
CHEoList( Handle ) == 0: Handle is the sceneHandle of the scene
the user is in.
------------------------------------------------------------------------------
*/
CHHandle_t chUserGetSceneHandle(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetNewData
DESCRIPTION:
Gets the value of the new data a user wants to set.
This function can only be called from within a
apchEventUserSetAttr or apchEventUserSetAttrLog event handling
function
It returns the new data the user wants to set.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetNewData(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetNickname
DESCRIPTION:
Gets the value of the nickname of a user.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetNickname(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetPasswd
DESCRIPTION:
Gets the value of the passwd of a user.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetPasswd(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetPort
DESCRIPTION:
Gets the value of the Port Number used by a the client program of a user.
RETURN VALUES:
CH_port_t rc == 0: The userHandle is invalid
otherwise: the Port Number the user is using in network
byte order
------------------------------------------------------------------------------
*/
CH_port_t chUserGetPort(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetSceneurl
DESCRIPTION:
Gets the value of the url of the scene a user is in or wants
to enter.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetSceneurl(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetText
DESCRIPTION:
Gets the value of the text a user wants to send.
This function can only be called from within a
apchEventUserText or apchEventUserTextLog event handling
function
It returns the text the user wants to send.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetText(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetUserid
DESCRIPTION:
Gets the value of the userid of a user.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetUserid(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetUrl
DESCRIPTION:
Gets the value of the url of the avatar used by a user.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chUserGetUrl(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetVersion
DESCRIPTION:
Gets the value of the Community Server protocol version number used by a user.
CyberGate up to Beta 5 uses 102.
CyberHubClient Beta 1 up to build 35 uses 103.
Passport 2.0 uses 105
RETURN VALUES:
CH_version_t rc == 0: The userHandle is invalid
otherwise: the Version Number the user is using.
------------------------------------------------------------------------------
*/
CH_version_t chUserGetVersion(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetApplicationData
DESCRIPTION:
Gets the value of the application data set for a user.
RETURN VALUES:
char * retptr == NULL: The userHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
char * chUserGetApplicationData(
CHHandle_t userHandle, /* r: handle for user structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetPosition
DESCRIPTION:
Gets the value of the position set by the user
RETURN VALUES:
CHPosition_t position: The position of the user
------------------------------------------------------------------------------
*/
CHPosition_t chUserGetPosition(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetOrientation
DESCRIPTION:
Gets the value of the orientation set by the user
RETURN VALUES:
CHOrientation_t orientation: The orientation of the user
------------------------------------------------------------------------------
*/
CHOrientation_t chUserGetOrientation(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chUserGetStatusBits
DESCRIPTION:
Gets the value of the status bits set by the user
RETURN VALUES:
CH_4byte_t statusbits: The status bits of the user
------------------------------------------------------------------------------
*/
CH_4byte_t chUserGetStatusBits(
CHHandle_t userHandle /* r: handle for user structure */
)
The following API Calls exist for Scene Objects.
9.1. Accesssing Existing Scenes per Session
contents
9.1.1. chSceneResetIter
contents
------------------------------------------------------------------------------
FUNCTION NAME: chSceneResetIter
DESCRIPTION:
Resets the list iterator of the scene list of a session to top of the list.
Call csSceneGetNext() to retrieve all scene objects.
RETURN VALUES:
int rc == -1: There is no scene at all
int rc == -2: The session handle used is invalid
------------------------------------------------------------------------------
*/
int chSceneResetIter(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneGetNext
DESCRIPTION:
The scene list iterator advances to the next list entry.
RETURN VALUES:
CHHandle_t Handle: Use the makro CHEoList on the sceneHandle returned.
CHEoList( Handle ) != 0: The End of the list has been reached.
CHEoList( Handle ) == 0: Handle is the sceneHandle of the next
element of the list.
------------------------------------------------------------------------------
*/
CHHandle_t chSceneGetNext(
CHHandle_t sessionHandle /* r: handle for session structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneGetUrl
DESCRIPTION:
Gets the value of the url of a scene
RETURN VALUES:
char * retptr == NULL: The sceneHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chSceneGetUrl(
CHHandle_t sceneHandle, /* r: handle for scene structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneGetName
DESCRIPTION:
Gets the value of the logical scene name of a scene
RETURN VALUES:
char * retptr == NULL: The sceneHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
const char * chSceneGetName(
CHHandle_t sceneHandle, /* r: handle for scene structure */
int * len /* w: length of value on return */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneGetNofUsers
DESCRIPTION:
Gets the number of users currently in a scene.
RETURN VALUES:
int rc < 0: The sceneHandle is invalid
otherwise: number of users in the scene
------------------------------------------------------------------------------
*/
int chSceneGetNofUsers(
CHHandle_t sceneHandle /* r: handle for scene structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneGetKeepalive
DESCRIPTION:
Gets the value of the keepalive flag of a scene.
The keepalive flag indicates whether a scene is made visible
because of a SHOWSCENE used in the indserver configuration file
RETURN VALUES:
int ret == 1: The scene is made visible at the idserver by
a SHOWSCENE statement in the idserver configuration.
int ret == 0: The scene is not mentioned in the idserver configuration
int rec < 0: The sceneHandle is invalid
------------------------------------------------------------------------------
*/
int chSceneGetKeepalive(
CHHandle_t sceneHandle /* r: handle for scene structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneGetApplicationData
DESCRIPTION:
Gets the value of the application data stored with a scene
RETURN VALUES:
char * retptr == NULL: The sceneHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
char * chSceneGetApplicationData(
CHHandle_t sceneHandle, /* r: handle for scene structure */
int * len /* w: length of value on return */
)
9.3.1. chSceneSetApplicationData
contents
------------------------------------------------------------------------------
FUNCTION NAME: chSceneSetApplicationData
DESCRIPTION:
Sets the value of the application data stored with a scene.
The application can read the data it has set for a scene by a call to
chSceneGetApplicationData.
This function does not malloc or free any data buffers,
nor does it do any consistency checks on the application data,
it simply lets the application set a pointer and an integer value
that can be retrieved later.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The sceneHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
int chSceneSetApplicationData(
CHHandle_t sceneHandle, /* r: handle for scene structure */
char *data, /* r: data to set for scene */
int datalen /* r: length of that data */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneSetTextEventStatus
DESCRIPTION:
This function allows to deactivate or activate text events for
a scene.
If the application subscribes to text events and calls this function
with the status parameter set to 1, no more text events will be
delivered for the scene specified.
Text events can be turned on again by calling this function
with the status parameter set to 0.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The sceneHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
int chSceneSetTextEventStatus(
CHHandle_t sceneHandle, /* r: handle for scene structure */
int status /* r: status to set */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSceneSetPositionEventStatus
DESCRIPTION:
This function allows to deactivate or activate position events for
a scene.
If the application subscribes to position events and calls this function
with the status parameter set to 1, no more position events will be
delivered for the scene specified.
Position events can be turned on again by calling this function
with the status parameter set to 0.
RETURN VALUES:
int rc == 0: call went ok
int rc == -1: The sceneHandle is invalid
otherwise: a pointer to the data requested, the out parameter len
contains the number of significant bytes in this buffer.
------------------------------------------------------------------------------
*/
int chSceneSetPositionEventStatus(
CHHandle_t sceneHandle, /* r: handle for scene structure */
int status /* r: status to set */
)
The Remote Access library is also part of the Community
Server API. See the
Remote Access Server documentation for details.
10.1. UDP Requests
contents
------------------------------------------------------------------------------
FUNCTION NAME: chEventUdpRequest
DESCRIPTION:
This function is called whenever a UDP client request comes in.
This is an example function, it is only called when the event
apchEventUdpRequest is registered via a call to chSessionRegisterEvent.
Use the RA server api call raGetArg to retrieve the arguments one by
one.
And use raSetResult to set result strings for the client application.
At least one result string has to be set, otherwise the client api
call returns with the error RA_ERR_DENIED.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventUdpRequest(
char *client, /* client that sent the request */
int inargc, /* number of arguments sent */
char *inargv[] /* pointerarray of arguments sent */
)
------------------------------------------------------------------------------
FUNCTION NAME: chEventHttpRequest
DESCRIPTION:
This function is called whenever a Http client request comes in.
This is an example function, it is only called when the event
apchEventHttpRequest is registered via a call to
chSessionRegisterEvent and the TCP listen port is specified
via the command line parameter -tp.
Use the RA server raGetHttp... API functions in order to read
the data sent by the client and use raSetHttpResult to set result
strings for the client application.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chEventHttpRequest(
char *connection /* r: connection that sent the request */
)
The Shared Event library is also part of the Community
Server API. The sesample subdirectory contains a complete example that uses all functions.
An HTML interface allows to send shared events and to test the server.
Test the example here. To test your own server,
install the setest server and insert your own Community Server and port in
contact.bxx.
All stored events of a scene are sent to a client after he enters the scene.
11.2. Configuration
contents
Shared events are stored if the server is started with the -se option. The seserver.cfg file specifies which events are stored forever or while a scene is populated. Each line in that file contains an entry
scenename#eventname lifetimeA wild card * at the end of scenename and eventname are possible. The lifetime is either P, which means while a scene is populated or F which means forever. The default configuration is
*#P_* P *#F_* Fwhich means that in all scenes on that server, all shared events starting with P_ are stored while someone is in the scene, and all shared events starting with F_ will be stored forever.
All events are stored in the file seserver.dat. Each line contains one event in the format:
scenename#eventname#type value
The file will be updated every minute after a change or whenever the server is stopped.
Events can be deleted from that file manually by just deleting the line while the server is stopped.
11.4. Functions
contents
11.4.1. chSharedEventIsShared
contents
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventIsShared
DESCRIPTION:
Checks whether the current text contains a shared event
Can be used in chEventUserText or chEventUserTextLog
RETURN VALUES:
int rc == 1: shared event
rc == 0: not a shared event
------------------------------------------------------------------------------
*/
int chSharedEventIsShared (
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventNoStore
DESCRIPTION:
The current event will not be stored.
Can be used only in chEventUserTextLog
RETURN VALUES:
int rc == 0: ok
rc == -1: not called inside chEventUserTextLog
------------------------------------------------------------------------------
*/
int chSharedEventNoStore(
CHHandle_t userHandle /* r: handle for user structure */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventSetPrecision
DESCRIPTION:
Set the float precision for EventCreateFloat.
Default is 4.
RETURN VALUES:
int rc == 0: ok
rc == -1: not a correct precision [0-9]
------------------------------------------------------------------------------
*/
int chSharedEventSetPrecision (
int precision /* r: precision value */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventGet
DESCRIPTION:
Get the current shared event. The ouput parameter will point to a static
buffer that will be replaced by the next call to that function.
Can be used in chEventUserText or chEventUserTextLog
RETURN VALUES:
int rc == 0: all out parameters are set for the event
rc ==-1: not a correct event
rc ==-2: parameter error
rc ==-3: no text or not a shared event
------------------------------------------------------------------------------
*/
int chSharedEventGet (
CHHandle_t userHandle, /* r: handle for user structure */
char **name, /* w: name of the event */
int *typei, /* w: type of the event */
char **value, /* w: value of the event */
int *noOfValues /* w: no of single values of the event, */
/* e.g. for an SFVec3f it would be 3 */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventCreateFloat
DESCRIPTION:
Create a shared event with float(s) as values. The output parameter will
point to a static buffer that will be replaced by the next call to that
function. The event can either be stored using chSharedEventStore or sent
using chUserSendText.
use for SFFloat, SFColor, SFVec2f, SFVec3f, SFRotation,
RETURN VALUES:
int rc == 0: the output parameters is set for the event
rc < 0: not a correct event, error code
------------------------------------------------------------------------------
*/
int chSharedEventCreateFloat (
char *name, /* r: name of the event */
int typei, /* r: type of the event */
float *value, /* r: array of floats */
int noOfValues, /* r: no of floats in value */
char **event /* w: output event */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventCreateString
DESCRIPTION:
Create a shared event with a string as a values. The output parameter will
point to a static buffer that will be replaced by the next call to that
function. The event can either be stored using chSharedEventStore or sent
using chUserSendText.
RETURN VALUES:
int rc == 0: the output parameters is set for the event
rc < 0: not a correct event, error code
------------------------------------------------------------------------------
*/
int chSharedEventCreateString (
char *name, /* r: name of the event */
int typei, /* r: type of the event */
char *value, /* r: string value */
char **event /* w: output event */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventCreateLong
DESCRIPTION:
Create a shared event with int(s) as values. The output parameter will
point to a static buffer that will be replaced by the next call to that
function. The event can either be stored using chSharedEventStore or sent
using chUserSendText.
Use for SFInt32, SFBool, SFTime
RETURN VALUES:
int rc == 0: the output parameters is set for the event
rc < 0: not a correct event, error code
------------------------------------------------------------------------------
*/
int chSharedEventCreateLong (
char *name, /* r: name of the event */
int typei, /* r: type of the event */
long value, /* r: long value */
char **event /* w; output event */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventGetFloat
DESCRIPTION:
read a value with float(s).
use for SFFloat, SFColor, SFVec2f, SFVec3f, SFRotation,
RETURN VALUES:
int rc > 0: the output parameters is set for the event,
and the number of values read is returned
rc < 0: not a correct event, error code
------------------------------------------------------------------------------
*/
int chSharedEventGetFloat (
char *value, /* r: value of the event */
float *floats, /* r: array of floats */
int noOfValues /* r: no of floats in floats */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventGetLong
DESCRIPTION:
read a value with long, int or bool(s).
Use for SFInt32, SFBool, SFTime
RETURN VALUES:
int rc == 1: the output parameters is set for the event,
rc < 0: not a correct event, error code
------------------------------------------------------------------------------
*/
int chSharedEventGetLong (
char *value, /* r: value of the event */
long *lvalue /* r: long value */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventGetString
DESCRIPTION:
read a value with string.
use for SFString,
RETURN VALUES:
int rc > 0: the output parameters is set for the event,
and the number of values read is returned
rc < 0: not a correct event, error code
------------------------------------------------------------------------------
*/
int chSharedEventGetString (
char *value, /* r: value of the event */
char **svalue /* w: string output */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventStore
DESCRIPTION:
Store the specified shared event for the scene. It will be stored only if
the persistency mode is "populated" or "forever". This means that the name
must match a name in seserver.cfg. If the event exists,
the value will be updated.
RETURN VALUES:
int rc == 0: event stored
rc < 0: error code, e.g. because event is not persistent
------------------------------------------------------------------------------
*/
int chSharedEventStore (
const char *scene,/* r: name of the scene */
char *event /* r: the event */
)
------------------------------------------------------------------------------
FUNCTION NAmE: chSharedEventFindStored
DESCRIPTION:
Find the event in the database and get the value.
RETURN VALUES:
int rc == 0: the out parameters are set for the event
rc < 0: not a correct event, error code
------------------------------------------------------------------------------
*/
int chSharedEventFindStored (
const char *scene,/* r: name of the scene */
char *name, /* r: name of the event */
int typei, /* r: type of the event */
char **value, /* w: value of the event */
int *noOfValues /* w: no of single values of the event,
e.g. for an SFVec3f it would be 3 */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventGetFirstStored
DESCRIPTION:
Get the first shared event from the database.
After calling chSharedEventDeleteStored or chSharedEventStore, the iteration must
be started again with chSharedEventGetFirstStored
RETURN VALUES:
int rc == 1: event found
rc == 0: no more events
rc < 0: error code
------------------------------------------------------------------------------
*/
int chSharedEventGetFirstStored (
char **scene, /* w: name of the scene */
char **name, /* w: name of the event */
int *typei, /* w: type of the event */
char **value, /* w: value of the event */
int *noOfValues /* w: no of single values of the event,
e.g. for an SFVec3f it would be 3 */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventGetNextStored
DESCRIPTION:
Get the next shared event from the database.
After calling chSharedEventDeleteStored or chSharedEventStore, the iteration must
be started again with chSharedEventResetIter
RETURN VALUES:
int rc == 1: event found
rc == 0: no more events
rc < 0: error code
------------------------------------------------------------------------------
*/
int chSharedEventGetNextStored (
char **scene, /* w: name of the scene */
char **name, /* w: name of the event */
int *typei, /* w: type of the event */
char **value, /* w: value of the event */
int *noOfValues /* w: no of single values of the event,
e.g. for an SFVec3f it would be 3 */
)
------------------------------------------------------------------------------
FUNCTION NAME: chSharedEventDeleteStored
DESCRIPTION:
Delete the specified shared event from the database.
RETURN VALUES:
int rc == 0: deleted
rc < 0: error code
------------------------------------------------------------------------------
*/
int chSharedEventDeleteStored (
const char *scene,/* r: name of the scene */
char *name, /* r: name of the event */
int typei /* r: type of the event */
)
The following functions allow an api server to create and maintain
users at the blaxxun Community Server it is connected to.
Users created can be sent into scenes, texts and shared events can be
sent for the users, the 3D position of the users can be manipulated.
12.1. Function chCSUserCreate
contents
------------------------------------------------------------------------------
FUNCTION NAME: chCSUserCreate
DESCRIPTION:
This function has to be called if a new user is to be created with
Community Server.
This function results in a call to the callback function specified.
The parameter puniqueid is optional, however the chCS interface will
only allow one user with the same puniqueid pnickname combination.
So if you want to be able to add more than one user with the same
nickname some id has to be chosen in order to make the combination
unique.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chCSUserCreate(
CHHandle_t psessionHandle, /* r: handle for session structure */
char *puniqueid, /* r: unique id used by user */
int puniqueidlen, /* r: length of that unique id */
int psocket, /* r: socket to send packets through */
char *puserid, /* r: userid for GetId packet */
int puseridlen, /* r: length of that id */
int pencryption, /* r: encryption used for passwd */
char *ppassword, /* r: password given by user */
int ppasswordlen, /* r: length of that password */
char *pattributes, /* r: application attributes of user */
int pattributeslen, /* r: length of these attributes */
char *psceneurl, /* r: url of scene to enter */
int psceneurllen, /* r: length if that url */
char *pnickname, /* r: nickname used by user */
int pnicknamelen, /* r: length of that nickname */
char *pinfo, /* r: public info of user */
int pinfolen, /* r: length of that info */
char *pgroup, /* r: group user wants to join */
int pgrouplen, /* r: length of that group */
char *purl, /* r: avatar url of user */
int purllen, /* r: length of that url */
CH_ip_t pip, /* r: ip address of user */
void (*pcallbackfunc)( /* r: function to call on error */
char *pnickname, /* r: nickname of user, as above */
int pnicknamelen,
char *psceneurl, /* r: url of scene to enter */
int psceneurllen,
char *puniqueid, /* r: unique id of user */
int puniqueidlen,
CH_id_t reason, /* r: reason for failure */
int code /* r: code of packet causing failure */
)
)
------------------------------------------------------------------------------
FUNCTION NAME: chCSUserDelete
DESCRIPTION:
Delete a user, sign the user off from Community Server, free all memory.
This function has to be called whenever a user has timed out with the
apserver or as a reaction to an error reported for the user
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chCSUserDelete(
char *pnickname, /* r: nickname used by user */
int pnicknamelen, /* r: length of that nickname */
char *puniqueid, /* r: unique id used by user */
int puniqueidlen /* r: length of that unique id */
)
------------------------------------------------------------------------------
FUNCTION NAME: chCSUserTextSend
DESCRIPTION:
Send a text for a user
RETURN VALUES:
int ret == 0; ok
otherwise user is unknown
------------------------------------------------------------------------------
*/
int chCSUserTextSend(
char *pnickname, /* r: nickname used by user */
int pnicknamelen, /* r: length of that nickname */
char *puniqueid, /* r: unique id used by user */
int puniqueidlen, /* r: length of that unique id */
char *ptopic, /* r: topic of group to send to */
int ptopiclen, /* r: length of that topic */
char *ptext, /* r: text to be sent */
int ptextlen /* r: length of that text */
)
------------------------------------------------------------------------------
FUNCTION NAME: chCSUserPositionSend
DESCRIPTION:
Send a position for a user
RETURN VALUES:
int ret == 0; ok
otherwise user is unknown
------------------------------------------------------------------------------
*/
int chCSUserPositionSend(
char *pnickname, /* r: nickname used by user */
int pnicknamelen, /* r: length of that nickname */
char *puniqueid, /* r: unique id used by user */
int puniqueidlen, /* r: length of that unique id */
CHPosition_t *pposition, /* r: position to send */
CHOrientation_t *porientation /* r: orientation ot send */
)
------------------------------------------------------------------------------
FUNCTION NAME: chCSUserStatusBitsSet
DESCRIPTION:
Sets the status bits for a user, the bits are sent to the server
with the next call to chCSUserPositionSend.
RETURN VALUES:
int ret == 0; ok
otherwise user is unknown
------------------------------------------------------------------------------
*/
int chCSUserStatusBitsSet(
char *pnickname, /* r: nickname used by user */
int pnicknamelen, /* r: length of that nickname */
char *puniqueid, /* r: unique id used by user */
int puniqueidlen, /* r: length of that unique id */
CH_4byte_t statusbits /* r: status bits to set */
)
------------------------------------------------------------------------------
FUNCTION NAME: chCSPeriodic
DESCRIPTION:
Periodic function of the apserver - Community Server interface.
This function is to be called every 3 seconds.
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void chCSPeriodic()
------------------------------------------------------------------------------
FUNCTION NAME: chCSUserDataHandler
DESCRIPTION:
This function has to be called whenever a chEventUsrData
occurs at the apiserver.
If the return code of this function reports that the packet
was not handled by this function the apiserver nneds to handle
the packet.
RETURN VALUES:
int handled == 0: The packet was not handled by this function
!= 0: The packet was handled by this function
------------------------------------------------------------------------------
*/
int chCSUserDataHandler(
int psocket,
char * packet, /* r: packet received */
int packetlen, /* r: length of that packet */
char * sender, /* r: socket address of sender */
int senderlen /* r: length of that address */
)
------------------------------------------------------------------------------
FUNCTION NAME: chCSCallbackFunction
DESCRIPTION:
Callback function for chCS... functions, this example
function only logs the event
Use your own function if you want to do some real callback handling.
------------------------------------------------------------------------------
*/
static void chCSCallbackFunction(
char *pnickname,
int pnicknamelen,
char *psceneurl,
int psceneurllen,
char *puniqueid,
int puniqueidlen,
CH_id_t reason,
int code
)
{
/*
* make sure the values printed are sane
*/
if( !pnickname )
{
pnickname = "unkown nickname";
pnicknamelen = strlen( pnickname );
}
if( !psceneurl )
{
psceneurl = "unkown sceneurl";
psceneurllen = strlen( psceneurl );
}
/*
* for each user created we get a callback when the corressponding
* setid packet arrives, i.e. the user has been allowed to enter
*/
if( code == IVS_SETID_CODE && reason )
{
/*
* this is actually a callback for the setid event
*/
PROCESS_LOG(( "APCS.LOG NEW ID %08x NNM \"%.*s\" SCN " "\"%.*s\"\n",
reason,
pnicknamelen, pnickname,
psceneurllen, psceneurl
));
return;
}
/*
* all other cases indicate error situations
*/
PROCESS_LOG(( "APCS.ERR chEventError N \"%.*s\" S "
"\"%.*s\" REASON %d CODE %d\n",
pnicknamelen, pnickname,
psceneurllen, psceneurl,
reason, code
));
} /* End of Function chCSCallbackFunction */
The following functions allow an api server get access to the
community database.
13.1. Function chDBInit
contents
------------------------------------------------------------------------------
FUNCTION NAME: chDBInit
DESCRIPTION:
Init the database connection. All parameters are optional.
Per default /csbin/community/global.cfg is used.
RETURN VALUES:
int rc == 0: ok
== -1: if parameters are missing or can't be read from global.cfg
or out of memory
------------------------------------------------------------------------------
*/
int chDBInit(
char * gcfg, /* alternative global.cfg to read the parameters */
char * host, /* host and aport of dbserver host to contact */
char * port /* if NULL, the global.cfg is used */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBGetError
DESCRIPTION:
Returns the error string set by the last database call
Use it to retrieve a detailed error string when a db call
fails.
RETURN VALUES:
char * retptr: points to the error string set.
------------------------------------------------------------------------------
*/
char * chDBGetError(
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBMget
DESCRIPTION:
Get multiple values from the database, all values returned are malloced.
RETURN VALUES:
int rc >= 0: number of arguments returned
< 0: an error, see raextern.h for error code details,
------------------------------------------------------------------------------
*/
int chDBMget(
char * datatype, /* r: type of data concerned */
char * keytype, /* r: keytype of value to get */
char * key, /* r: value of the key */
int nattr, /* r: number of attribute value pairs */
char ** attr, /* r: attributes to get record */
char ** avals /* w: vals of those attributes */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBGet
DESCRIPTION:
Get a value from the database
RETURN VALUES:
char * retptr == NULL; database error
otherwise
The value or "" if not set,
the value is always given back in malloced memory
------------------------------------------------------------------------------
*/
char * chDBGet(
char * datatype, /* r: type of data concerned */
char * keytype, /* r: keytype of value to get */
char * key, /* r: value of that key */
char * attrname /* r: name of attribute to get from record */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBList
DESCRIPTION:
List keys with attributes from a database
RETURN VALUES:
int rc >= 0: number of arguments returned
< 0: an error, see raextern.h for error code details,
------------------------------------------------------------------------------
*/
int chDBList(
char * datatype, /* r: type of data concerned */
char * keytype, /* r: Key type defining the list order */
char * startkeytype, /* r: Key type to position on a record */
char * startkeyvalue, /* r: start value for the key */
char * number, /* r: number of keys to list */
char * direction, /* r: direction of list */
char * keyfilter, /* r: filter for keys */
int nattr, /* r: number of attributes to get */
char ** attr, /* r: attributes to get */
char ** vals /* w: vals of found keys and req attributes */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBMset
DESCRIPTION:
Set values in the database
RETURN VALUES:
int rc == 0: set of attribute is ok
!= 0: an error, see raextern.h for error code details,
------------------------------------------------------------------------------
*/
int chDBMset(
char * datatype, /* r: type of data concerned */
char * keytype, /* r: keytype of value to set */
char * key, /* r: value of the key */
int nattr, /* r: number of attribute value pairs */
char ** attr, /* r: attributes to set */
char ** avals /* r: vals of those attributes */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBMadd
DESCRIPTION:
Add/substract values to existing integer attribute values in
the database.
All attributes changed with this function have to be integer values,
i.e. strings representing the integer as hex value.
The value to add/substract has to be a decimal string.
RETURN VALUES:
int rc == 0: change of attribute is ok
!= 0: an error, see raextern.h for error code details,
------------------------------------------------------------------------------
*/
int chDBMadd(
char * datatype, /* r: type of data concerned */
char * keytype, /* r: keytype of value to set */
char * key, /* r: value of the key */
int nattr, /* r: number of attribute value pairs */
char ** attr, /* r: attributes to set */
char ** avals /* r: vals to add/sub to those attributes */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBAdd
DESCRIPTION:
Add/substract a value to a single existing integer attribute in
the database. Return the value of the attribute after the add/substract.
The attribute changed with this function has to be an integer value,
i.e. a string representing the integer as hex value.
The value to add/substract has to be a decimal string.
RETURN VALUES:
int rc == 0: change of attribute is ok
!= 0: an error, see raextern.h for error code details,
------------------------------------------------------------------------------
*/
int chDBAdd(
char * datatype, /* r: type of data concerned */
char * keytype, /* r: keytype of value to change */
char * key, /* r: value of the key */
char * attr, /* r: attribute to change */
char * aval, /* r: value to add/sub to the attribute */
char ** result /* w: result of add/sub in malloced memory */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBIns
DESCRIPTION:
Create a record in the database
RETURN VALUES:
int rc == 0: the new record was created
int rc == 1: a record with the same key already exists
< 0: an error, see raextern.h for error code details,
------------------------------------------------------------------------------
*/
int chDBIns(
char * datatype, /* r: type of data concerned */
int nkeys, /* r: number of key value pairs */
char ** keys, /* r: keys of the record */
char ** vals, /* r: vals of those keys */
int nattr, /* r: number of attribute value pairs */
char ** attr, /* r: attributes to set */
char ** avals /* r: vals of those attributes */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBDelete
DESCRIPTION:
Delete a key from the database
RETURN VALUES:
int rc == 0: the record was deleted
< 0: an error, see raextern.h for error code details,
------------------------------------------------------------------------------
*/
int chDBDelete(
char * datatype, /* r: type of data concerned */
char * keytype, /* r: keytype of value to delete */
char * key /* r: value of key */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBMgetCached
DESCRIPTION:
Read a list of attributes of an entry in the so database table.
The attribute list is cached in the soserver for one hour.
The result is malloced.
RETURN VALUES:
int rc >= 0: number of arguments returned
< 0: an error, handle it,
------------------------------------------------------------------------------
*/
int chDBMgetCached(
char * datatype, /* r: type of data concerned */
char * kty, /* r: Keytype of value to get */
char * val, /* r: value of the key */
int nattr, /* r: number of attribute value pairs */
char ** attr, /* r: attributes to get */
char ** avals /* w: vals of those attributes */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBGetCached
DESCRIPTION:
Read an attributes of an entry in the database.
The attribute is cached for one hour.
RETURN VALUES:
NULL in case of an error
char * value: one pointer
------------------------------------------------------------------------------
*/
char * chDBGetCached(
char * datatype, /* r: type of data concerned */
char * key, /* r: Key of value to get */
char * val, /* r: value of the key */
char * aname /* r: name of attributes to read */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBSetCacheTime
DESCRIPTION:
set the time in seconds for expiration of cache entries.
default is one hour.
------------------------------------------------------------------------------
*/
void chDBSetCacheTime(
time_t newtime /* r: expiration time of cache entries */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBGetObjectFromScene
DESCRIPTION:
Get the key id and datatype of an object from a chat scene url
Dty and key are returned in static memory.
RETURN VALUES:
1 if key found
0 if no object
------------------------------------------------------------------------------
*/
int chDBGetObjectFromScene(
char * scene, /* r: scene name */
char ** dty, /* w: datatype of object */
char ** key /* w: key value of object */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBGetParent
DESCRIPTION:
Get the parent of an object in the homesteading hierachy
e.g. block for home.
The parentkey is malloced.
RETURN VALUES:
1 if parent found
0 if no parent
------------------------------------------------------------------------------
*/
int chDBGetParent(
char * datatype, /* r: type of data concerned */
char * key, /* r: Key of value to get */
char ** parentdty, /* w: datatype of parent */
char ** parentkey /* w: keyid of parent */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBGetMemberType
DESCRIPTION:
chDBGetMemberType - see whether the user is an administrator,
member or visitor
it uses the g_Admins value from global.cfg
additionally the member record is checked in the db
and id and role are read.
Id and role are returned in static memory.
RETURN VALUES:
rc == CHDB_IS_BAD: neither visitor nor member
rc == CHDB_IS_VISITOR: user is visitor
rc == CHDB_IS_MEMBER: user is member
rc == CHDB_IS_ADMIN: user is an administrator
------------------------------------------------------------------------------
*/
int chDBGetMemberType(
char * nickname, /* the nickname of the member */
char ** memberid, /* w: id of the member */
char ** role /* w: the role of the member */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBCheckRole
DESCRIPTION:
chDBCheckRole - check a members role string against a rolemask of an
object
If the rolemask of the object is empty access
is allowed
RETURN VALUES:
int rc = 1: The member has at least one of the roles necessary
int rc = -1: Roles are necessary and the member does not have them
The member is explicitly excluded
otherwise: There are no roles required, let the member access
------------------------------------------------------------------------------
*/
int chDBCheckRole(
char * mrole, /* role string of the member */
char * orole /* role string of the object */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBCheckRights
DESCRIPTION:
Check the rights of a member for an object specified.
Either the nickname or the member id must be specified.
This function handles the recursive check for CHDB_ACCESS_RCHANGE correctly.
The ID of the member is taken from the global variable chDB_Id.
The indirect rights check based on PKT, PDT and PKE is handled correctly.
RETURN VALUES:
int rc: A combination of the
CHDB_ACCESS_READ,
CHDB_ACCESS_WRITE
CHDB_ACCESS_OWN
CHDB_ACCESS_RCHANGE
bits showing the access for the member
------------------------------------------------------------------------------
*/
int chDBCheckRights(
int mtype, /* r: type of the member (optional) */
char * memid, /* r: member id (optional) */
char * nickname , /* r: nickname of the member */
char * rolemask, /* r: member's role mask, (optional) */
char * odatatype, /* r: datatype of object to check */
char * okeytype, /* r: keytype of object to check */
char * okey, /* r: key of object to check */
int accesstype /* r: accesstype to check for */
)
------------------------------------------------------------------------------
FUNCTION NAME: chDBUnscrambleCookie
unscramble a cookie into its components
RETURN:
Sets pointers to static memory holding the values
------------------------------------------------------------------------------
*/
int chDBUnscrambleCookie(
char * passwd, /* r: input buffer */
char ** cookietag, /* w: tag read from cookie */
char ** cookieid, /* w: id read from cookie */
char ** cookienickname, /* w: nickname read from cookie */
char ** cookiepasswd, /* w: passwd read from cookie */
char ** cookietime, /* w: time read from cookie */
char ** cookielang, /* w: user language preference */
char ** cookiecache /* w: user cache string */
)