Initialisation and global routines

Functions
int	glencode_set_param (PARAM *p)
int	pvlock (PARAM *p)
int	pvunlock (PARAM *p)
int	pvsystem (const char *command)
void	pvGetLocalTime (pvTime *pvtime)
int	pvIsAccessAllowed (const char *adr, int trace)
int	pvSendVersion (PARAM *p)
int	pvXYAllocate (PARAM *p, int n)
int	getIntegers (const char *text, IntegerArray *ia)
int	getFloats (const char *text, FloatArray *fa)
const char *	getTextFromText (const char *text)
int	pvSetXY (PARAM *p, int i, float x, float y)
int *	pvGetSocketPointer (PARAM *p)
int	pvInitInternal (PARAM *p)
int	pvInit (int ac, char **av, PARAM *p)
int	pvAccept (PARAM *p)
int	pvCreateThread (PARAM *p, int s)
int	pvGetInitialMask (PARAM *p)
int	pvMain (PARAM *p)
int	pvSetCleanup (PARAM *p, int(*cleanup)(void *), void *app_data)
char *	pvGetEvent (PARAM *p)
int	pvPollEvent (PARAM *p, char *event)
int	pvWait (PARAM *p, const char *pattern)
int	pvGlUpdate (PARAM *p, int id)
int	pvSleep (int milliseconds)
int	pvWarning (PARAM *p, const char *text)
int	pvMainFatal (PARAM *p, const char *text)
int	pvThreadFatal (PARAM *p, const char *text)
int	pvScreenHint (PARAM *p, int w, int h)
int	pvSetMouseShape (PARAM *p, int shape)
int	pvSetWhatsThis (PARAM *p, int id, const char *text)
int	pvWhatsThisPrintf (PARAM *p, int id, const char *format,...)
int	pvClientCommand (PARAM *p, const char *command, const char *filename, int downloadFile=0)
int	pvWriteTextToFileAtClient (PARAM *p, const char *text, const char *filename)
int	pvZoomMask (PARAM *p, int percent)
int	pvSetManualUrl (PARAM *p, const char *url)
int	pvSelectLanguage (PARAM *p, const char *section)

Detailed Description

These routines are used for initialisation. And also some global usable routines are available.

Function Documentation

getFloats()

int getFloats	(	const char *	text,
		FloatArray *	fa
	)

Get integer array from string for script language

getIntegers()

int getIntegers	(	const char *	text,
		IntegerArray *	ia
	)

Get integer array from string for script language

getTextFromText()

const char* getTextFromText

(

const char *

text

)

Get text in parentesis from text for script language

glencode_set_param()

int glencode_set_param

(

PARAM *

p

)

pvAccept()

int pvAccept

(

PARAM *

p

)

see pvInit

pvClientCommand()

int pvClientCommand	(	PARAM *	p,
		const char *	command,
		const char *	filename,
		int	downloadFile = 0
	)

Run command on client.
command := pdf | img | svg | txt | csv | html | audio | video | save_as
See view.pdf, view.img, view.svg ... within pvbrowser options.

pvCreateThread()

int pvCreateThread	(	PARAM *	p,
		int	s
	)

see pvInit

pvGetEvent()

char* pvGetEvent

(

PARAM *

p

)

If it is necessary to cleanup your application when the main worker thread terminates
you can set an exit handler that receives the data in app_data.
Call this function in pvMain. See also pvMain.

pvGetInitialMask()

int pvGetInitialMask

(

PARAM *

p

)

Get the initial mask the user wants to see
p->initial_mask is a string identifying the initial mask 

pvGetLocalTime()

void pvGetLocalTime

(

pvTime *

pvtime

)

Get local time

pvGetSocketPointer()

int* pvGetSocketPointer

(

PARAM *

p

)

Get a pointer to the socket for script language

pvGlUpdate()

int pvGlUpdate	(	PARAM *	p,
		int	id
	)

update OpenGL widget

pvInit()

int pvInit	(	int	ac,
		char **	av,
		PARAM *	p
	)

(Test) pvInit must be called in main(). It interprets the command line switches that it knows.
Afterwards you can interpret your command line switches. It is possible to set p.user to data
of your choice. This data will be available in the worker threads. (Caution: the worker threads are
only allowed to read the p.user data because it is shared among all clients)
Then there must be a while(1) in which new clients are accepted. For each client a new thread
is created.

 int main(int ac, char **av)
 {
 PARAM p;
 int   s;

   pvInit(ac,av,&p);
   // here you may interpret ac,av and set p.user to your data
   while(1)
   {
     s = pvAccept(&p);
     if(s != -1) pvCreateThread(&p,s);
   }
   return 0;
 }

pvInitInternal()

int pvInitInternal

(

PARAM *

p

)

see pvInit
Init for script languages

pvIsAccessAllowed()

int pvIsAccessAllowed	(	const char *	adr,
		int	trace
	)

Test if access is allowed by files "allow.ipv4" and "deny.ipv4" in your local directory
adr := dottet ip address
trace = 1 print messages on stdout
trace = 0 do not print messages on stdout
return = 1 access allowed
return = 0 access is not allowed

Example allow.ipv4:
1.0.0.127/32         # allow localhost
192.168.1.0/24       # allow 192.168.1.0 - 192.168.1.255
insert more areas here

Example deny.ipv4:
deny a individual address

192.168.2.14/32
insert more areas here

The number behind the / is the number of significant bits of the ip address.
Every pvserver will evaluate "allow.ipv4 and "deny.ipv4" when client connects.

pvlock()

int pvlock

(

PARAM *

p

)

If you access variables that are global to the server or
if you want to use malloc() and free()
you must surround the operations with
pvlock() and pvunlock()
because these operations are not thread save.

pvMain()

int pvMain

(

PARAM *

p

)

pvMain is your main worker thread. It could look as follows.
The main worker thread is never closed. It will be closed automatically when the client disconnects.

int pvMain(PARAM *p)
{
int ret;

  // here you can initialize your worker thread
  pvSetCleanup(p,your_exit_handler,your_app_data); // if cleanup is necessary
  pvResize(p,0,970,600);  // this will resize your working area
  ret = showMask1(p);
  while(1)
  {
    switch(ret)
    {
      case 1:
        ret = showMask1(p);
        break;
      case 2:
        ret = showMask2(p);
        break;
      case 3:
        ret = showMask3(p);
        break;
      default:
        return 0;
    }
  }
}

pvMainFatal()

int pvMainFatal	(	PARAM *	p,
		const char *	text
	)

Output a fatal message and terminate the whole server.

pvPollEvent()

int pvPollEvent	(	PARAM *	p,
		char *	event
	)

This function will return the next event as soon as it is available.
The maximum wait time is p->sleep in milliseconds (default 100).
You can specify a different wait time on the commandline (-sleep=1000)

Example:

 int showMask1(PARAM *p)
 {
 DATA d;
 char event[MAX_EVENT_LENGTH];
 int  i;
 char text[MAX_EVENT_LENGTH];

   defineMask1(p);
   readData1(&d); // from shared memory or out of database
   showData1(p,&d);
   while(1)
   {
     pvPollEvent(p,event);
     switch(pvParseEvent(event, &i, text))
     {
       case NULL_EVENT:
         readData1(&d); // from shared memory or out of database
         showData1(p,&d);
         break;
       case BUTTON_EVENT:
         ...
         break;
       case TEXT_EVENT:
         ...
         break;
       default:
         printf("UNKNOWN_EVENT id=\%d \%s\\n",i,text);
         break;
     }
   }
 }

pvScreenHint()

int pvScreenHint	(	PARAM *	p,
		int	w,
		int	h
	)

Output a screenHint for calculating the zoom factor
Optimal screen width=w height=h .

pvSelectLanguage()

int pvSelectLanguage	(	PARAM *	p,
		const char *	section
	)

Select the section for language translations with the pvtr() macro.

processviewserver.h defines the macro
#define pvtr(txt) txt

If you use something like pvSetText(p,id,pvtr("Hello World"));
the above macro will return the original untranslated text.

If you #include "rlinifile.h" the macro pvtr will be redefined to
#define pvtr(txt) rltranslate2(p->lang_section,txt)
Thus the subroutine rltranslate2() will be called.
This routine will also return the untranslated text until you call

rlSetTranslator("GERMAN","translation.ini");

within your main() program.
The above call to rlSetTranslator() will read the ini file "translation.ini" and
set the default section to "GERMAN".
This will be the default language within your pvserver.

If your translation.ini looks like
[GERMAN]
Hello World=Hallo Welt

the call to pvtr("Hello World") will return "Hallo Welt".
If there is no translation for a phrase then the original untranslated text will be returned.

Now you might want that each client can choose his own language.
This can be done by calling

pvSelectLanguage(p,"YOUR_LANGUAGE");

within pvMain() or one of your masks.
Hint: after changing the language you should return from the mask
with a return value that will call the mask again and will show the mask in the new language.

If the strings within the ini file include "=" characters you must quote them as "\=".
Also tabs and newline characters must be quoted as "\t" and "\n".
Within the graphical designer of pvdevelop you must use 2 quotes instead of one "\\=", "\\t" and "\\n".

Background:
We use an INI file for language translation.
The section names the language.
The original text is used to select the translation.

pvSendVersion()

int pvSendVersion

(

PARAM *

p

)

Send version of pvserver to client

pvSetCleanup()

int pvSetCleanup	(	PARAM *	p,
		int(*)(void *)	cleanup,
		void *	app_data
	)

If it is necessary to cleanup your application when the main worker thread terminates
you can set an exit handler that receives the data in app_data.
Call this function in pvMain. See also pvMain.

pvSetManualUrl()

int pvSetManualUrl	(	PARAM *	p,
		const char *	url
	)

Set the URL which will be used for Help->Manual within pvbrowser.
default: index.html
You could also set the URL of a webserver which hosts your documentation.
Example:
pvSetManualUrl(p,"http://your.server.org");

pvSetMouseShape()

int pvSetMouseShape	(	PARAM *	p,
		int	shape
	)

Set mouse shape
MouseShape.

pvSetWhatsThis()

int pvSetWhatsThis	(	PARAM *	p,
		int	id,
		const char *	text
	)

Set whatsThis text
Allowed Widgets: all Widgets

pvSetXY()

int pvSetXY	(	PARAM *	p,
		int	i,
		float	x,
		float	y
	)

Set x,y array for script language

pvSleep()

int pvSleep

(

int

milliseconds

)

Sleep for milliseconds.

pvsystem()

int pvsystem

(

const char *

command

)

Same as system(command); but portable

pvThreadFatal()

int pvThreadFatal	(	PARAM *	p,
		const char *	text
	)

Output a fatal message and terminate the worker thread.

pvunlock()

int pvunlock

(

PARAM *

p

)

If you access variables that are global to the server or
if you want to use malloc() and free()
you must surround the operations with
pvlock() and pvunlock()
because these operations are not thread save.

pvWait()

int pvWait	(	PARAM *	p,
		const char *	pattern
	)

waits for an event.

pvWarning()

int pvWarning	(	PARAM *	p,
		const char *	text
	)

Output a warning message.

pvWhatsThisPrintf()

int pvWhatsThisPrintf	(	PARAM *	p,
		int	id,
		const char *	format,
			...
	)

printf whatsThis text
Allowed Widgets: all Widgets

pvWriteTextToFileAtClient()

int pvWriteTextToFileAtClient	(	PARAM *	p,
		const char *	text,
		const char *	filename
	)

Write "text" to a file "filename" in temp directory at client.

pvXYAllocate()

int pvXYAllocate	(	PARAM *	p,
		int	n
	)

Allocate x,y array for script language

pvZoomMask()

int pvZoomMask	(	PARAM *	p,
		int	percent
	)

Zoom the whole mask.
Zoom factor in percent.