maapi.h File Reference

---

Detailed Description

The MoSync API is a general compact API with a small footprint.

With this API it should be possible to do most things, although, there may still be some functionality missing. If you would like a specific function added, please do send us a mail.

In future versions of MoSync an extension API will be provided that will allow you to create your own custom syscalls.

Some Caveats:

The Runtime expects alignment rules to be followed. Writing or reading to unaligned memory will cause a MoSync Panic.

Some functions may also cause a panic if they are passed incorrect parameters. A complete reference of these panics can be found here.

The codepage for functions that use strings is platform-dependent beyond 7-bit ASCII. Most use Latin-1, but you should still be wary.

Additional notes:

There are different types of handles: Connection, Store and Resource. They are all represented as positive signed integers. When a handle is passed to a function, it must have the proper type.

Each MoSync program has a Resource array. It is acccessed and manipulated by certain syscalls, but it cannot be accessed directly. Each resource (aka Object) is represented by a handle. There are different types of resources, for example Image, Binary data, Sound or Placeholder. A placeholder object is not a real object, but just a handle which you can use to construct new objects dynamically. Resources can also be defined at compile time, by using MoSync's resource compiler. Placeholders can either be defined at compile time using a resource compiler directive or created dynamically at runtime using maCreatePlaceholder(). See the tutorials, examples and the resource compiler reference documentation for more information.

There is an event queue which contains keypad events and results from asynchronous operations. Use maWait() and maGetEvent() to handle it.

There are different types of connection operations. For each connection, only one of each type of operation may be active at the same time.

Classes
struct	MAPoint2d
struct	MARect
struct	MACopyData
struct	MAConnAddrInet4
struct	MABtAddr
struct	MAConnAddrBt
struct	MAConnAddr
struct	MAConnEventData
struct	MAEvent
struct	MAPanicReport
struct	MABtDevice
struct	MAUUID
struct	MABtServiceSize
struct	MABtService
struct	MALocation
struct	MAFrameBufferInfo
Bluetooth discovery
These structures and functions are used for asynchronous device and service discovery. Only one operation may be active at a time. When a device or service is found, its information is stored in internal buffers for later retrieval by maBtGetNewDevice() or maBtGetNewService(), then a BT event is generated. A BT event is also generated when the operation is complete. A BT event contains the state of the Bluetooth Discovery operation. This is <0 (a CONNERR value) on failure, 0 while still working and ((number of devices/services found) + 1) on success. The buffers are cleared when the respective operation is started, so any devices or services left over in the buffers from an earlier operation will be lost.
void *	memset (void *dst, int val, ulong size)
void *	memcpy (void *dst, const void *src, ulong size)
int	strcmp (const char *str1, const char *str2)
char *	strcpy (char *dst, const char *src)
double	__adddf3 (double a, double b)
double	__subdf3 (double a, double b)
double	__muldf3 (double a, double b)
double	__divdf3 (double a, double b)
double	__negdf2 (double a)
int	__fixdfsi (double a)
double	__floatsidf (int a)
double	f2d (float a)
int	dcmp (double a, double b)
float	__addsf3 (float a, float b)
float	__subsf3 (float a, float b)
float	__mulsf3 (float a, float b)
float	__divsf3 (float a, float b)
float	__negsf2 (float a)
int	__fixsfsi (float a)
float	__floatsisf (int a)
float	d2f (double a)
int	fcmp (float a, float b)
double	sin (double x)
double	cos (double x)
double	tan (double x)
double	sqrt (double x)
int	maSetColor (int rgb)
void	maSetClipRect (int left, int top, int width, int height)
void	maGetClipRect (MARect *out)
void	maPlot (int posX, int posY)
void	maLine (int startX, int startY, int endX, int endY)
void	maFillRect (int left, int top, int width, int height)
void	maFillTriangleStrip (const MAPoint2d *points, int count)
void	maFillTriangleFan (const MAPoint2d *points, int count)
MAExtent	maGetTextSize (const char *str)
void	maDrawText (int left, int top, const char *str)
void	maUpdateScreen (void)
void	maResetBacklight (void)
MAExtent	maGetScrSize (void)
void	maDrawImage (MAHandle image, int left, int top)
void	maDrawRGB (const MAPoint2d *dstPoint, const void *src, const MARect *srcRect, int scanlength)
void	maDrawImageRegion (MAHandle image, const MARect *srcRect, const MAPoint2d *dstPoint, int transformMode)
MAExtent	maGetImageSize (MAHandle image)
void	maGetImageData (MAHandle image, void *dst, const MARect *srcRect, int scanlength)
MAHandle	maSetDrawTarget (MAHandle image)
int	maFindLabel (const char *name)
int	maCreateImageFromData (MAHandle placeholder, MAHandle data, int offset, int size)
int	maCreateImageRaw (MAHandle placeholder, const void *src, MAExtent size, int alpha)
int	maCreateDrawableImage (MAHandle placeholder, int width, int height)
int	maCreateData (MAHandle placeholder, int size)
MAHandle	maCreatePlaceholder (void)
void	maDestroyObject (MAHandle handle)
int	maGetDataSize (MAHandle data)
void	maReadData (MAHandle data, void *dst, int offset, int size)
void	maWriteData (MAHandle data, const void *src, int offset, int size)
void	maCopyData (const MACopyData *params)
MAHandle	maOpenStore (const char *name, int flags)
int	maWriteStore (MAHandle store, MAHandle data)
int	maReadStore (MAHandle store, MAHandle placeholder)
void	maCloseStore (MAHandle store, int remove)
MAHandle	maConnect (const char *url)
void	maConnClose (MAHandle conn)
void	maConnRead (MAHandle conn, void *dst, int size)
void	maConnWrite (MAHandle conn, const void *src, int size)
void	maConnReadToData (MAHandle conn, MAHandle data, int offset, int size)
void	maConnWriteFromData (MAHandle conn, MAHandle data, int offset, int size)
int	maConnGetAddr (MAHandle conn, MAConnAddr *addr)
MAHandle	maHttpCreate (const char *url, int method)
void	maHttpSetRequestHeader (MAHandle conn, const char *key, const char *value)
int	maHttpGetResponseHeader (MAHandle conn, const char *key, char *buffer, int bufSize)
void	maHttpFinish (MAHandle conn)
int	maLoadResources (MAHandle data)
void	maLoadProgram (MAHandle data, int reload)
int	maGetKeys (void)
int	maGetEvent (MAEvent *event)
void	maWait (int timeout)
int	maTime (void)
int	maLocalTime (void)
int	maGetMilliSecondCount (void)
int	maFreeObjectMemory (void)
int	maTotalObjectMemory (void)
int	maVibrate (int ms)
void	maExit (int result) __attribute__((noreturn))
void	maPanic (int result, const char *message) __attribute__((noreturn))
int	maSoundPlay (MAHandle sound_res, int offset, int size)
void	maSoundStop (void)
int	maSoundIsPlaying (void)
int	maSoundGetVolume (void)
void	maSoundSetVolume (int vol)
int	maInvokeExtension (int function, int a, int b, int c)
int	maIOCtl (int function, int a, int b, int c)
static int	maCheckInterfaceVersion (int hash)
static int	maReportCallStack (void)
static void	maProtectMemory (const void *start, int length)
static void	maUnprotectMemory (const void *start, int length)
static void	maSetMemoryProtection (int enable)
static int	maGetMemoryProtection (void)
static int	maGetBatteryCharge (void)
static int	maLockKeypad (void)
static int	maUnlockKeypad (void)
static int	maKeypadIsLocked (void)
static int	maWriteLog (const void *src, int size)
static int	maBtStartDeviceDiscovery (int names)
static int	maBtGetNewDevice (MABtDevice *d)
static int	maBtStartServiceDiscovery (const MABtAddr *address, const MAUUID *uuid)
static int	maBtGetNextServiceSize (MABtServiceSize *dst)
static int	maBtGetNewService (MABtService *dst)
static int	maBtCancelDiscovery (void)
static int	maLocationStart (void)
static int	maLocationStop (void)
static int	maPlatformRequest (const char *url)
static int	maSendTextSMS (const char *dst, const char *msg)
static int	maFrameBufferGetInfo (MAFrameBufferInfo *info)
static int	maFrameBufferInit (const void *data)
static int	maFrameBufferClose (void)
static int	maSendToBackground (void)
static int	maBringToForeground (void)
static int	maGetSystemProperty (const char *key, char *buf, int size)
Defines
#define	MAIDL_HASH   ((int)0x167e12d8)
	A hash of the abstract representation of the API described in this file. Identifiers, declarations and definitions are included in the calculation of the hash, but documentation is not.
#define	ATTRIBUTE(a, func)   func __attribute__ ((a))
#define	GCCATTRIB(a)   __attribute__ ((a))
#define	MOSYNC_API
#define	EXTENT_Y(e)   ((short)(e))
	Returns the height of an MAExtent.
#define	EXTENT_X(e)   ((short)((e) >> 16))
	Returns the width of an MAExtent.
#define	EXTENT(x, y)   ((MAExtent)((((int)(x)) << 16) | ((y) & 0xFFFF)))
	Creates an MAExtent.
#define	TRANS_NONE   0
	The image is copied unchanged.
#define	TRANS_ROT90   5
	The image is rotated clockwise by 90 degrees.
#define	TRANS_ROT180   3
	The image is rotated clockwise by 180 degrees.
#define	TRANS_ROT270   6
	The image is rotated clockwise by 270 degrees.
#define	TRANS_MIRROR   2
	The image is reflected about its vertical center.
#define	TRANS_MIRROR_ROT90   7
	The image is reflected about its vertical center, then rotated clockwise by 90 degrees.
#define	TRANS_MIRROR_ROT180   1
	The image is reflected about its vertical center, then rotated clockwise by 180 degrees.
#define	TRANS_MIRROR_ROT270   4
	The image is reflected about its vertical center, then rotated clockwise by 270 degrees.
#define	HANDLE_SCREEN   0
	This handle refers to the back buffer, which is initially black.
#define	HANDLE_LOCAL   0
#define	RES_OUT_OF_MEMORY   -1
#define	RES_BAD_INPUT   -2
#define	RES_OK   1
#define	MAS_CREATE_IF_NECESSARY   1
#define	STERR_GENERIC   -2
	Generic error.
#define	STERR_FULL   -3
	The storage medium is full.
#define	STERR_NONEXISTENT   -5
	The store does not exist.
#define	CONNERR_GENERIC   -2
	Generic error.
#define	CONNERR_MAX   -3
	The maximum number of open connections allowed has been reached.
#define	CONNERR_DNS   -4
	DNS resolution error.
#define	CONNERR_INTERNAL   -5
	Internal error. Please report any occurrences to Mobile Sorcery.
#define	CONNERR_CLOSED   -6
	The connection was closed by the remote peer.
#define	CONNERR_READONLY   -7
	You attempted to write to a read-only connection.
#define	CONNERR_FORBIDDEN   -8
	The OS does not trust you enough to let you open this connection.
#define	CONNERR_UNINITIALIZED   -9
	No operation has been started yet.
#define	CONNERR_CONLEN   -10
	The Content-Length header could not be found.
#define	CONNERR_URL   -11
	You supplied a malformed URL.
#define	CONNERR_UNAVAILABLE   -12
	The protocol is not available.
#define	CONNERR_CANCELED   -13
	You canceled the operation.
#define	CONNERR_PROTOCOL   -14
	The server gave an invalid response.
#define	CONNERR_NETWORK   -15
	The network connection could not be established.
#define	CONNERR_NOHEADER   -16
	The requested header could not be found.
#define	CONNERR_USER   -1000000
#define	CONNOP_READ   1
#define	CONNOP_WRITE   2
#define	CONNOP_CONNECT   5
#define	CONNOP_FINISH   11
#define	CONN_MAX   32
	The maximum number of open connections allowed.
#define	BTADDR_LEN   6
#define	CONN_FAMILY_INET4   1
#define	CONN_FAMILY_BT   2
#define	HTTP_GET   1
#define	HTTP_POST   2
#define	HTTP_HEAD   3
#define	MAK_UNKNOWN   0
#define	MAK_FIRST   0
#define	MAK_BACKSPACE   8
#define	MAK_TAB   9
#define	MAK_CLEAR   12
#define	MAK_RETURN   13
#define	MAK_PAUSE   19
#define	MAK_ESCAPE   27
#define	MAK_SPACE   32
#define	MAK_EXCLAIM   33
#define	MAK_QUOTEDBL   34
#define	MAK_POUND   35
#define	MAK_HASH   35
#define	MAK_GRID   35
#define	MAK_DOLLAR   36
#define	MAK_AMPERSAND   38
#define	MAK_QUOTE   39
#define	MAK_LEFTPAREN   40
#define	MAK_RIGHTPAREN   41
#define	MAK_ASTERISK   42
#define	MAK_STAR   42
#define	MAK_PLUS   43
#define	MAK_COMMA   44
#define	MAK_MINUS   45
#define	MAK_PERIOD   46
#define	MAK_SLASH   47
#define	MAK_0   48
#define	MAK_1   49
#define	MAK_2   50
#define	MAK_3   51
#define	MAK_4   52
#define	MAK_5   53
#define	MAK_6   54
#define	MAK_7   55
#define	MAK_8   56
#define	MAK_9   57
#define	MAK_COLON   58
#define	MAK_SEMICOLON   59
#define	MAK_LESS   60
#define	MAK_EQUALS   61
#define	MAK_GREATER   62
#define	MAK_QUESTION   63
#define	MAK_AT   64
#define	MAK_LEFTBRACKET   91
#define	MAK_BACKSLASH   92
#define	MAK_RIGHTBRACKET   93
#define	MAK_CARET   94
#define	MAK_UNDERSCORE   95
#define	MAK_BACKQUOTE   96
#define	MAK_A   97
#define	MAK_B   98
#define	MAK_C   99
#define	MAK_D   100
#define	MAK_E   101
#define	MAK_F   102
#define	MAK_G   103
#define	MAK_H   104
#define	MAK_I   105
#define	MAK_J   106
#define	MAK_K   107
#define	MAK_L   108
#define	MAK_M   109
#define	MAK_N   110
#define	MAK_O   111
#define	MAK_P   112
#define	MAK_Q   113
#define	MAK_R   114
#define	MAK_S   115
#define	MAK_T   116
#define	MAK_U   117
#define	MAK_V   118
#define	MAK_W   119
#define	MAK_X   120
#define	MAK_Y   121
#define	MAK_Z   122
#define	MAK_DELETE   127
#define	MAK_KP0   256
#define	MAK_KP1   257
#define	MAK_KP2   258
#define	MAK_KP3   259
#define	MAK_KP4   260
#define	MAK_KP5   261
#define	MAK_KP6   262
#define	MAK_KP7   263
#define	MAK_KP8   264
#define	MAK_KP9   265
#define	MAK_KP_PERIOD   266
#define	MAK_KP_DIVIDE   267
#define	MAK_KP_MULTIPLY   268
#define	MAK_KP_MINUS   269
#define	MAK_KP_PLUS   270
#define	MAK_KP_ENTER   271
#define	MAK_KP_EQUALS   272
#define	MAK_UP   273
#define	MAK_DOWN   274
#define	MAK_RIGHT   275
#define	MAK_LEFT   276
#define	MAK_INSERT   277
#define	MAK_HOME   278
#define	MAK_END   279
#define	MAK_PAGEUP   280
#define	MAK_PAGEDOWN   281
#define	MAK_FIRE   284
#define	MAK_SOFTLEFT   285
#define	MAK_SOFTRIGHT   286
#define	MAK_PEN   291
#define	MAK_BACK   292
#define	MAK_MENU   293
#define	MAK_RSHIFT   303
#define	MAK_LSHIFT   304
#define	MAK_RCTRL   305
#define	MAK_LCTRL   306
#define	MAK_RALT   307
#define	MAK_LALT   308
#define	MAKB_LEFT   0x00001
#define	MAKB_UP   0x00002
#define	MAKB_RIGHT   0x00004
#define	MAKB_DOWN   0x00008
#define	MAKB_FIRE   0x00010
#define	MAKB_SOFTLEFT   0x00020
#define	MAKB_SOFTRIGHT   0x00040
#define	MAKB_0   0x00080
#define	MAKB_1   0x00100
#define	MAKB_2   0x00200
#define	MAKB_3   0x00400
#define	MAKB_4   0x00800
#define	MAKB_5   0x01000
#define	MAKB_6   0x02000
#define	MAKB_7   0x04000
#define	MAKB_8   0x08000
#define	MAKB_9   0x10000
#define	MAKB_ASTERISK   0x20000
#define	MAKB_STAR   0x20000
#define	MAKB_HASH   0x40000
#define	MAKB_POUND   0x40000
#define	MAKB_GRID   0x40000
#define	MAKB_CLEAR   0x80000
#define	EVENT_BUFFER_SIZE   128
#define	EVENT_CLOSE_TIMEOUT   2000
	In milliseconds.
#define	EVENT_TYPE_CLOSE   1
#define	EVENT_TYPE_KEY_PRESSED   2
#define	EVENT_TYPE_KEY_RELEASED   3
#define	EVENT_TYPE_CONN   4
	Connection.
#define	EVENT_TYPE_BT   5
	Bluetooth discovery.
#define	EVENT_TYPE_POINTER_PRESSED   8
#define	EVENT_TYPE_POINTER_RELEASED   9
#define	EVENT_TYPE_POINTER_DRAGGED   10
#define	EVENT_TYPE_FOCUS_LOST   13
#define	EVENT_TYPE_FOCUS_GAINED   14
#define	EVENT_TYPE_LOCATION   16
	Has MAEvent::data point to an MALocation.
#define	EVENT_TYPE_LOCATION_PROVIDER   17
	MAEvent::state is one of the MA_LPS constants.
#define	EVENT_TYPE_SCREEN_CHANGED   21
#define	RUNTIME_MORE   1
	The MoSync Reference Environment, also known as the Emulator.
#define	RUNTIME_JAVA   2
	Java ME.
#define	RUNTIME_SYMBIAN   3
	Symbian.
#define	RUNTIME_WINCE   4
	Windows CE, also known as Windows Mobile.
#define	REPORT_PANIC   1
	Caused by a MoSync Panic. MAPanicReport::code is the panic code.
#define	REPORT_EXCEPTION   2
	Caused by a native exception. MAPanicReport::string describes the exception.
#define	REPORT_PLATFORM_CODE   3
	Caused by a platform-specific error. MAPanicReport::code is valid.
#define	REPORT_USER_PANIC   4
#define	REPORT_TIMEOUT   5
	Caused by the Close event timeout. Neither code or string are valid.
#define	MA_LOC_NONE   1
#define	MA_LOC_INVALID   2
#define	MA_LOC_UNQUALIFIED   3
#define	MA_LOC_QUALIFIED   4
#define	MA_LPS_AVAILABLE   1
#define	MA_LPS_TEMPORARILY_UNAVAILABLE   2
#define	MA_LPS_OUT_OF_SERVICE   3
#define	IOCTL_UNAVAILABLE   -1
Typedefs
typedef char *	MAString
typedef void *	MAAddress
typedef int	MAHandle
typedef int	MAExtent
typedef unsigned char	byte
typedef unsigned short	ushort
typedef unsigned int	uint
typedef unsigned long	ulong

---

Define Documentation

#define MAIDL_HASH   ((int)0x167e12d8)

A hash of the abstract representation of the API described in this file. Identifiers, declarations and definitions are included in the calculation of the hash, but documentation is not.

#define ATTRIBUTE (  a, func   )     func __attribute__ ((a))

#define GCCATTRIB (  a   )     __attribute__ ((a))

#define MOSYNC_API

#define EXTENT_Y (  e   )     ((short)(e))

Returns the height of an MAExtent.

#define EXTENT_X (  e   )     ((short)((e) >> 16))

Returns the width of an MAExtent.

#define EXTENT (  x, y   )     ((MAExtent)((((int)(x)) << 16) | ((y) & 0xFFFF)))

Creates an MAExtent.

#define TRANS_NONE   0

The image is copied unchanged.

#define TRANS_ROT90   5

The image is rotated clockwise by 90 degrees.

#define TRANS_ROT180   3

The image is rotated clockwise by 180 degrees.

#define TRANS_ROT270   6

The image is rotated clockwise by 270 degrees.

#define TRANS_MIRROR   2

The image is reflected about its vertical center.

#define TRANS_MIRROR_ROT90   7

The image is reflected about its vertical center, then rotated clockwise by 90 degrees.

#define TRANS_MIRROR_ROT180   1

The image is reflected about its vertical center, then rotated clockwise by 180 degrees.

#define TRANS_MIRROR_ROT270   4

The image is reflected about its vertical center, then rotated clockwise by 270 degrees.

#define HANDLE_SCREEN   0

This handle refers to the back buffer, which is initially black.

#define HANDLE_LOCAL   0

#define RES_OUT_OF_MEMORY   -1

#define RES_BAD_INPUT   -2

#define RES_OK   1

#define MAS_CREATE_IF_NECESSARY   1

#define STERR_GENERIC   -2

Generic error.

#define STERR_FULL   -3

The storage medium is full.

#define STERR_NONEXISTENT   -5

The store does not exist.

#define CONNERR_GENERIC   -2

Generic error.

#define CONNERR_MAX   -3

The maximum number of open connections allowed has been reached.

#define CONNERR_DNS   -4

DNS resolution error.

#define CONNERR_INTERNAL   -5

Internal error. Please report any occurrences to Mobile Sorcery.

#define CONNERR_CLOSED   -6

The connection was closed by the remote peer. Happens when HTTP servers finish sending data.

#define CONNERR_READONLY   -7

You attempted to write to a read-only connection.

#define CONNERR_FORBIDDEN   -8

The OS does not trust you enough to let you open this connection.

#define CONNERR_UNINITIALIZED   -9

No operation has been started yet.

#define CONNERR_CONLEN   -10

The Content-Length header could not be found.

#define CONNERR_URL   -11

You supplied a malformed URL.

#define CONNERR_UNAVAILABLE   -12

The protocol is not available.

#define CONNERR_CANCELED   -13

You canceled the operation.

#define CONNERR_PROTOCOL   -14

The server gave an invalid response.

#define CONNERR_NETWORK   -15

The network connection could not be established.

#define CONNERR_NOHEADER   -16

The requested header could not be found.

#define CONNERR_USER   -1000000

If you wish to share the CONNERR codespace, use values below this for your own error codes.

#define CONNOP_READ   1

#define CONNOP_WRITE   2

#define CONNOP_CONNECT   5

#define CONNOP_FINISH   11

#define CONN_MAX   32

The maximum number of open connections allowed.

#define BTADDR_LEN   6

#define CONN_FAMILY_INET4   1

#define CONN_FAMILY_BT   2

#define HTTP_GET   1

#define HTTP_POST   2

#define HTTP_HEAD   3

#define MAK_UNKNOWN   0

#define MAK_FIRST   0

#define MAK_BACKSPACE   8

#define MAK_TAB   9

#define MAK_CLEAR   12

#define MAK_RETURN   13

#define MAK_PAUSE   19

#define MAK_ESCAPE   27

#define MAK_SPACE   32

#define MAK_EXCLAIM   33

#define MAK_QUOTEDBL   34

#define MAK_POUND   35

#define MAK_HASH   35

#define MAK_GRID   35

#define MAK_DOLLAR   36

#define MAK_AMPERSAND   38

#define MAK_QUOTE   39

#define MAK_LEFTPAREN   40

#define MAK_RIGHTPAREN   41

#define MAK_ASTERISK   42

#define MAK_STAR   42

#define MAK_PLUS   43

#define MAK_COMMA   44

#define MAK_MINUS   45

#define MAK_PERIOD   46

#define MAK_SLASH   47

#define MAK_0   48

#define MAK_1   49

#define MAK_2   50

#define MAK_3   51

#define MAK_4   52

#define MAK_5   53

#define MAK_6   54

#define MAK_7   55

#define MAK_8   56

#define MAK_9   57

#define MAK_COLON   58

#define MAK_SEMICOLON   59

#define MAK_LESS   60

#define MAK_EQUALS   61

#define MAK_GREATER   62

#define MAK_QUESTION   63

#define MAK_AT   64

#define MAK_LEFTBRACKET   91

#define MAK_BACKSLASH   92

#define MAK_RIGHTBRACKET   93

#define MAK_CARET   94

#define MAK_UNDERSCORE   95

#define MAK_BACKQUOTE   96

#define MAK_A   97

#define MAK_B   98

#define MAK_C   99

#define MAK_D   100

#define MAK_E   101

#define MAK_F   102

#define MAK_G   103

#define MAK_H   104

#define MAK_I   105

#define MAK_J   106

#define MAK_K   107

#define MAK_L   108

#define MAK_M   109

#define MAK_N   110

#define MAK_O   111

#define MAK_P   112

#define MAK_Q   113

#define MAK_R   114

#define MAK_S   115

#define MAK_T   116

#define MAK_U   117

#define MAK_V   118

#define MAK_W   119

#define MAK_X   120

#define MAK_Y   121

#define MAK_Z   122

#define MAK_DELETE   127

#define MAK_KP0   256

#define MAK_KP1   257

#define MAK_KP2   258

#define MAK_KP3   259

#define MAK_KP4   260

#define MAK_KP5   261

#define MAK_KP6   262

#define MAK_KP7   263

#define MAK_KP8   264

#define MAK_KP9   265

#define MAK_KP_PERIOD   266

#define MAK_KP_DIVIDE   267

#define MAK_KP_MULTIPLY   268

#define MAK_KP_MINUS   269

#define MAK_KP_PLUS   270

#define MAK_KP_ENTER   271

#define MAK_KP_EQUALS   272

#define MAK_UP   273

#define MAK_DOWN   274

#define MAK_RIGHT   275

#define MAK_LEFT   276

#define MAK_INSERT   277

#define MAK_HOME   278

#define MAK_END   279

#define MAK_PAGEUP   280

#define MAK_PAGEDOWN   281

#define MAK_FIRE   284

#define MAK_SOFTLEFT   285

#define MAK_SOFTRIGHT   286

#define MAK_PEN   291

#define MAK_BACK   292

#define MAK_MENU   293

#define MAK_RSHIFT   303

#define MAK_LSHIFT   304

#define MAK_RCTRL   305

#define MAK_LCTRL   306

#define MAK_RALT   307

#define MAK_LALT   308

#define MAKB_LEFT   0x00001

#define MAKB_UP   0x00002

#define MAKB_RIGHT   0x00004

#define MAKB_DOWN   0x00008

#define MAKB_FIRE   0x00010

#define MAKB_SOFTLEFT   0x00020

#define MAKB_SOFTRIGHT   0x00040

#define MAKB_0   0x00080

#define MAKB_1   0x00100

#define MAKB_2   0x00200

#define MAKB_3   0x00400

#define MAKB_4   0x00800

#define MAKB_5   0x01000

#define MAKB_6   0x02000

#define MAKB_7   0x04000

#define MAKB_8   0x08000

#define MAKB_9   0x10000

#define MAKB_ASTERISK   0x20000

#define MAKB_STAR   0x20000

#define MAKB_HASH   0x40000

#define MAKB_POUND   0x40000

#define MAKB_GRID   0x40000

#define MAKB_CLEAR   0x80000

#define EVENT_BUFFER_SIZE   128

#define EVENT_CLOSE_TIMEOUT   2000

In milliseconds.

#define EVENT_TYPE_CLOSE   1

This event is posted when the operating system sends MoSync a command to exit. Causes include the OS shutting down and OS-controlled user commands. See also: maGetEvent()

#define EVENT_TYPE_KEY_PRESSED   2

#define EVENT_TYPE_KEY_RELEASED   3

#define EVENT_TYPE_CONN   4

Connection.

#define EVENT_TYPE_BT   5

Bluetooth discovery.

#define EVENT_TYPE_POINTER_PRESSED   8

#define EVENT_TYPE_POINTER_RELEASED   9

#define EVENT_TYPE_POINTER_DRAGGED   10

#define EVENT_TYPE_FOCUS_LOST   13

While MoSync doesn't have focus, no key events will arrive and the screen will not be updated. If the keypad is locked, no application will have focus. See also: maLockKeypad

#define EVENT_TYPE_FOCUS_GAINED   14

#define EVENT_TYPE_LOCATION   16

Has MAEvent::data point to an MALocation.

#define EVENT_TYPE_LOCATION_PROVIDER   17

MAEvent::state is one of the MA_LPS constants.

#define EVENT_TYPE_SCREEN_CHANGED   21

#define RUNTIME_MORE   1

The MoSync Reference Environment, also known as the Emulator.

#define RUNTIME_JAVA   2

Java ME.

#define RUNTIME_SYMBIAN   3

Symbian.

#define RUNTIME_WINCE   4

Windows CE, also known as Windows Mobile.

#define REPORT_PANIC   1

Caused by a MoSync Panic. MAPanicReport::code is the panic code.

#define REPORT_EXCEPTION   2

Caused by a native exception. MAPanicReport::string describes the exception.

#define REPORT_PLATFORM_CODE   3

Caused by a platform-specific error. MAPanicReport::code is valid.

#define REPORT_USER_PANIC   4

Caused by a call to maPanic(). MAPanicReport::code and MAPanicReport::string are the parameters from the call.

#define REPORT_TIMEOUT   5

Caused by the Close event timeout. Neither code or string are valid.

#define MA_LOC_NONE   1

#define MA_LOC_INVALID   2

#define MA_LOC_UNQUALIFIED   3

#define MA_LOC_QUALIFIED   4

#define MA_LPS_AVAILABLE   1

Availability status code: the location provider is available.

#define MA_LPS_TEMPORARILY_UNAVAILABLE   2

Availability status code: the location provider is temporarily unavailable. Temporary unavailability means that the method is unavailable due to reasons that can be expected to possibly change in the future and the provider to become available. An example is not being able to receive the signal because the signal used by the location method is currently being obstructed, e.g. when deep inside a building for satellite based methods. However, a very short transient obstruction of the signal should not cause the provider to toggle quickly between TEMPORARILY_UNAVAILABLE and AVAILABLE.

#define MA_LPS_OUT_OF_SERVICE   3

Availability status code: the location provider is out of service. Being out of service means that the method is unavailable and the implementation is not able to expect that this situation would change in the near future. An example is when using a location method implemented in an external device and the external device is detached.

#define IOCTL_UNAVAILABLE   -1

---

Typedef Documentation

typedef char* MAString

typedef void* MAAddress

typedef int MAHandle

typedef int MAExtent

typedef unsigned char byte

typedef unsigned short ushort

typedef unsigned int uint

typedef unsigned long ulong

---

Function Documentation

void* memset (  void *  dst, int  val, ulong  size )

Sets size bytes, starting at dst, to the specified value, interpreted as an unsigned char. Returns: dst.

void* memcpy (  void *  dst, const void *  src, ulong  size )

Copies the values of size bytes from the location pointed by src directly to the memory block pointed by dst. The underlying type of the objects pointed by both the source and destination pointers are irrelevant for this function; The result is a binary copy of the data. The function does not check for any terminating null character in source - it always copies exactly size bytes. To avoid overflows, the size of the arrays pointed by both the destination and source parameters, shall be at least size bytes, and should not overlap (for overlapping memory blocks, memmove() is a safe approach). Returns: dst.

int strcmp (  const char *  str1, const char *  str2 )

Compares the C string str1 to the C string str2. This function starts comparing the first character of each string. If they are equal to each other, it continues with the following pairs until the characters differ or until a terminanting null-character is reached. Returns: An integral value indicating the relationship between the strings: A zero value indicates that both strings are equal. A value greater than zero indicates that the first character that does not match has a greater value in str1 than in str2. A value less than zero indicates the opposite.

char* strcpy (  char *  dst, const char *  src )

Copies the C string pointed by src into the array pointed by dst, including the terminating null character. To avoid overflows, the size of the array pointed by dst shall be long enough to contain the same C string as src (including the terminating null character), and should not overlap in memory with src. Returns: dst.

double __adddf3 (  double  a, double  b )

Returns a + b.

double __subdf3 (  double  a, double  b )

Returns a - b.

double __muldf3 (  double  a, double  b )

Returns a * b.

double __divdf3 (  double  a, double  b )

Returns a / b. If b == 0, a MoSync Panic is thrown.

double __negdf2 (  double  a  )

Returns -a.

int __fixdfsi (  double  a  )

Returns the integer part of a.

double __floatsidf (  int  a  )

Returns the double representation of a.

double f2d (  float  a  )

Returns the double representation of a.

int dcmp (  double  a, double  b )

Returns >0 if a > b, 0 if a == b and <0 if a < b. If either argument is Not a Number, the result is undefined.

float __addsf3 (  float  a, float  b )

Returns a + b.

float __subsf3 (  float  a, float  b )

Returns a - b.

float __mulsf3 (  float  a, float  b )

Returns a * b.

float __divsf3 (  float  a, float  b )

Returns a / b. If b == 0, a MoSync Panic is thrown.

float __negsf2 (  float  a  )

Returns -a.

int __fixsfsi (  float  a  )

Returns the integer part of a.

float __floatsisf (  int  a  )

Returns the float representation of a.

float d2f (  double  a  )

Returns the double representation of a.

int fcmp (  float  a, float  b )

Returns >0 if a > b, 0 if a == b and <0 if a < b. If either argument is Not a Number, the result is undefined.

double sin (  double  x  )

Returns the sine of x. Parameters: x  An angle in radians.

double cos (  double  x  )

Returns the cosine of x. Parameters: x  An angle in radians.

double tan (  double  x  )

Returns the tangent of x. Parameters: x  An angle in radians.

double sqrt (  double  x  )

Returns the square root of x.

int maSetColor (  int  rgb  )

Sets the color used by drawing functions. Returns previous color. Initial color is 0 (black). Parameters: rgb  A color in RGB8 format (0xRRGGBB). The top byte is ignored.

void maSetClipRect (  int  left, int  top, int  width, int  height )

Sets the clipping rectangle for the current draw target. The screen and every drawable image each maintains a clipping rectangle. Drawing operations have no effect outside the clipping rectangle. The default clipping rectangle covers the entire draw target, so that clipping occurs at the draw target's edges.

void maGetClipRect (  MARect *  out  )

Returns the clipping rectangle for the current draw target.

void maPlot (  int  posX, int  posY )

Draws a single pixel using the current color.

void maLine (  int  startX, int  startY, int  endX, int  endY )

Draws a line using the current color.

void maFillRect (  int  left, int  top, int  width, int  height )

Draws a filled rectangle using the current color. Width and height must be greater than zero.

void maFillTriangleStrip (  const MAPoint2d *  points, int  count )

Draws a filled triangle strip using the current color. Parameters: points  A pointer to an array of count MAPoint2d:s representing the vertices of the strip. count  The count of vertices in the strip. Must be at least 3.

void maFillTriangleFan (  const MAPoint2d *  points, int  count )

Draws a filled triangle fan using the current color. Parameters: points  A pointer to an array of count MAPoint2d:s representing the vertices of the fan. count  The count of vertices in the fan. Must be at least 3.

MAExtent maGetTextSize (  const char *  str  )

Returns the size in pixels of Latin-1 text as it would appear on-screen.

void maDrawText (  int  left, int  top, const char *  str )

Draws Latin-1 text using the current color.

void maUpdateScreen (  void   )

Copies the back buffer to the physical screen.

void maResetBacklight (  void   )

Normally, a phone's backlight turns itself off after a few seconds of the user not pressing any keys. To avoid this behaviour, call this function periodically. As the timeout period is different for every device, and sometimes even user-configurable, it's recommended that you call this function at least once every 500 milliseconds to ensure that the light stays on at all times.

MAExtent maGetScrSize (  void   )

Returns the screen size.

void maDrawImage (  MAHandle  image, int  left, int  top )

Draws an image. It it placed on the draw target with the top left corner according to the parameters.

void maDrawRGB (  const MAPoint2d *  dstPoint, const void *  src, const MARect *  srcRect, int  scanlength )

Draws an image. The source is an array of ints that represent pixels in XRGB format. Parameters: dstPoint  The top-left point on the draw target. src  The address to the source image. srcRect  The portion of the source image to be drawn. scanlength  The width, in pixels, of the image represented by the source array.

void maDrawImageRegion (  MAHandle  image, const MARect *  srcRect, const MAPoint2d *  dstPoint, int  transformMode )

Draws a portion of an image using a transformation. Parameters: image  The source image. srcRect  The portion of the source image to be drawn. Must not exceed the bounds of the source image. dstPoint  The top-left point on the draw target. transformMode  One of the TRANS constants. See also: maDrawImage

MAExtent maGetImageSize (  MAHandle  image  )

Returns the size of an image.

void maGetImageData (  MAHandle  image, void *  dst, const MARect *  srcRect, int  scanlength )

Copies an image into an array of ints that represent pixels in ARGB format. The destination rectangle is defined as { 0,0, srcRect.width, srcRect.height }. Parts of the destination array that are outside the destination rectangle are not modified. If srcRect is outside the bounds of the source image, or if srcRect.width is greater than scanlength, a MoSync Panic is thrown. Parameters: image  The handle to the source image. dst  The address of the destination array. scanlength  The width of the image, in pixels, represented by the destination array. srcRect  The portion of the source image to be copied.

MAHandle maSetDrawTarget (  MAHandle  image  )

Sets the current draw target. The handle must be a drawable image or HANDLE_SCREEN, which represents the back buffer. The initial draw target is the back buffer. If an image is set as draw target, its object handle goes into flux, which prevents its destruction or use as a source in maDrawImage. When a different draw target is set, the image's handle is restored. Returns the the previously set draw target. See also: maCreateDrawableImage()

int maFindLabel (  const char *  name  )

Finds the label resource with the specified name and returns its index. If it is not found, -1 is returned.

int maCreateImageFromData (  MAHandle  placeholder, MAHandle  data, int  offset, int  size )

Creates an image object using encoded data from a data object. All platforms support the PNG format. Some platforms may also support JPEG and/or GIF. Parameters: placeholder  The placeholder for the image object that is to be created. data  The data object that holds the encoded data. offset  The offset in the data object where the encoded data begins. size  The size in bytes of the encoded data. Returns: RES_OK if succeded and RES_OUT_OF_MEMORY or RES_BAD_INPUT if failed.

int maCreateImageRaw (  MAHandle  placeholder, const void *  src, MAExtent  size, int  alpha )

Creates an image object using raw ARGB data. Parameters: placeholder  The placeholder for the image object that is to be created. src  Address of the raw data. 4 bytes per pixel, format 0xAARRGGBB. size  The size in pixels of the image, constructed using the EXTENT() macro. alpha  Non-zero if the resulting image should have an alpha channel, zero otherwise. Returns: RES_OK if succeded and RES_OUT_OF_MEMORY if failed.

int maCreateDrawableImage (  MAHandle  placeholder, int  width, int  height )

Creates a drawable image of the specified size. A drawable image has no alpha channel, which is to say, no transparency. Its initial contents are undefined, so you should draw onto the entire surface to be sure what will happen when you draw this image onto something else. Parameters: placeholder  The resource handle of the new image. width  Width, in pixels, of the new image. Must be > 0. height  Height, in pixels, of the new image. Must be > 0. See also: maSetDrawTarget() Returns: RES_OK if succeded and RES_OUT_OF_MEMORY if failed.

int maCreateData (  MAHandle  placeholder, int  size )

Creates a data object of the specified size, in bytes. Its initial contents are undefined. Returns: RES_OK if succeded and RES_OUT_OF_MEMORY if failed.

MAHandle maCreatePlaceholder (  void   )

Creates a new placeholder and returns the handle to it.

void maDestroyObject (  MAHandle  handle  )

Destroys an object of any type. The handle becomes a placeholder.

int maGetDataSize (  MAHandle  data  )

Returns the size, in bytes, of a data object.

void maReadData (  MAHandle  data, void *  dst, int  offset, int  size )

Reads size bytes from a data object, starting at offset, into memory pointed to by dst. Warning: Do not attempt to read zero bytes or out of bounds; it is not supported and will result in a MoSync Panic.

void maWriteData (  MAHandle  data, const void *  src, int  offset, int  size )

Writes size bytes to a data object, starting at offset, from memory pointed to by src.

void maCopyData (  const MACopyData *  params  )

Copies size bytes from data object src to dst, at the specified offsets.

MAHandle maOpenStore (  const char *  name, int  flags )

Opens a permanent data store, optionally creates one if it doesn't exist already. Returns a Store MAHandle on success. Returns STERR_NONEXISTENT if !(flags & MAS_CREATE_IF_NECESSARY) and the store does not exist. Returns another STERR code if the store could not be opened for another reason. Parameters: name  The name of the store. A store name must have between 1 and 32 characters, inclusive, and must not contain any of the following characters: "\:;?*' flags  A combination of MAS flags, or zero.

int maWriteStore (  MAHandle  store, MAHandle  data )

Writes the contents of a data object to a store. Destroys any data currently in the store. Returns > 0 on success, STERR_FULL if the storage system is full, or another STERR code if the write failed for another reason. Parameters: store  The store to write to. data  The data object to read from.

int maReadStore (  MAHandle  store, MAHandle  placeholder )

Creates a data object and copies the contents of a store to it. Use maGetDataSize to get the size of the data. Parameters: store  The store to read from. placeholder  The placeholder handle where a data object will be created. Returns: RES_OK if succeded and RES_OUT_OF_MEMORY if failed.

void maCloseStore (  MAHandle  store, int  remove )

Closes a store. Also removes that store if remove is non-zero.

MAHandle maConnect (  const char *  url  )

Asynchronously opens a connection using the specified URL. A URL takes the following form: <protocol>://<address>[:<port>]<parameters> The following protocols are supported: socket, which is TCP and has no parameters. ssl, which is an encrypted TCP connection. It has no parameters. http, which is HTTP/1.0 GET. When using HTTP, you need not specify the port; it defaults to port 80. Its parameters is the document path (for example, "/index.html"). Writing to a http connection is not allowed. https, which is an encrypted HTTP GET. It has the same parameters as http. btspp, which is Bluetooth Serial Port and has no parameters. For the socket and http protocols, <address> can be either a decimal, dot-delimited (.) IPv4 address or a standard Domain Name, while <port> is a decimal number from 1 to 65535. In the socket protocol, certain ports are protected on certain platforms and cannot be used, most notably port 80 on Java ME. In this case, use http instead. On a few devices, using ports numbered below 1024 may cause system crashes. Therefore, it is advisable to use ports above 1024 if you can choose. For the btspp protocol, <address> is 12 hexadecimal digits and <port> is a decimal number from 1 to 30. Example TCP url: socket://www.example.com:23 Example HTTP url: http://www.example.com/directory/document.html Example Bluetooth url: btspp://001dbe15e455:9 To find Bluetooth addresses, use the Bluetooth discovery API. See maBtStartDeviceDiscovery(). The result of the operation will be delivered in a CONN event, with MAConnEventData::opType set to CONNOP_CONNECT. The success value is > 0. For the http protocol, the success value is the HTTP response code. When you're done with the connection, maConnClose() must be called to free the resources associated with the handle. This must be done even if the connect operation failed. There is a limit of CONN_MAX open connection handles at any time, so if you keep opening connections without closing them, you'll eventually recieve the CONNERR_MAX error code instead of new connection handles. Returns: The connecting handle >0, or one of the CONNERR values. See also: maGetEvent Warning: At this time, encrypted connections are supported only on Java runtimes.

void maConnClose (  MAHandle  conn  )

Closes a connection, freeing any resources associated with the handle. Cancels any active operations on the connection. Such operations will finish with CONNERR_CANCELED.

void maConnRead (  MAHandle  conn, void *  dst, int  size )

Asynchronously reads at least one and at most size bytes from a connection to memory. The result of the operation will be delivered in a CONN event, with MAConnEventData::opType set to CONNOP_READ. The success value is the number of bytes read. See also: maGetEvent

void maConnWrite (  MAHandle  conn, const void *  src, int  size )

Asynchronously writes size bytes to a connection from memory. The result of the operation will be delivered in a CONN event, with MAConnEventData::opType set to CONNOP_WRITE. The success value is > 0. See also: maGetEvent

void maConnReadToData (  MAHandle  conn, MAHandle  data, int  offset, int  size )

Asynchronously reads at least one and at most size bytes from a connection to a data object, starting at the specified offset. During the read, the data object being written to will be in flux. Any attempt to access it will result in a Panic. The result of the operation will be delivered in a CONN event, with MAConnEventData::opType set to CONNOP_READ. The success value is is the number of bytes read. See also: maGetEvent

void maConnWriteFromData (  MAHandle  conn, MAHandle  data, int  offset, int  size )

Asynchronously writes size bytes to a connection from a data object, starting at the specified offset. During the write, the data object being read from will be in flux. Any attempt to access it will result in a Panic. The result of the operation will be delivered in a CONN event, with MAConnEventData::opType set to CONNOP_WRITE. The success value is > 0. See also: maGetEvent

int maConnGetAddr (  MAHandle  conn, MAConnAddr *  addr )

Retrieves the address of a connection. On server connections, you'll get the local address. On normal connections, you'll get the remote address. You can pass HANDLE_LOCAL to retrieve the local address. In that case, you must set MAConnAddr::family before calling this function, to tell it which address to retrieve. Also, the port member is not set. Returns: < 0 on error.

MAHandle maHttpCreate (  const char *  url, int  method )

Creates an unfinished HTTP/1.0 connection. You cannot read from this connection until it's been Finished. Before then, you can set request headers. After, you can get response headers. POST connections are special; they let you write to the connection before it's Finished. The first write causes the underlying TCP connection to be established and request headers transmitted. After the first write has begun, you may no longer set request headers. Parameters: url  An HTTP or HTTPS URL. See maConnect() for the exact form. method  HTTP_GET, HTTP_POST or HTTP_HEAD. Returns: An unfinished HTTP connection handle >0, or a CONNERR value. See also: maHttpFinish

void maHttpSetRequestHeader (  MAHandle  conn, const char *  key, const char *  value )

Sets a request header of an HTTP connection. Overwrites any existing header with the same key. The keys is case-insensitive. If the connection's method is HTTP_POST, it must not have been written to. Parameters: conn  An unfinished HTTP connection handle. key  The name of the header. value  The new value of the header.

int maHttpGetResponseHeader (  MAHandle  conn, const char *  key, char *  buffer, int  bufSize )

Stores an HTTP response header in the specified buffer. The buffer may be too small to contain the header and the terminating zero; in that case, the buffer will not be filled and you should create a bigger buffer and call this function again. Parameters: conn  A finished HTTP connection handle. key  The name of the header. Case-insensitive. buffer  A string buffer. bufSize  The size of the buffer, in bytes. Returns: The length of the header value, excluding the terminating zero, or CONNERR_NOHEADER if the header doesn't exist.

void maHttpFinish (  MAHandle  conn  )

Asynchronously finishes an HTTP connection. This entails making the underlying TCP connection and sending request headers, unless that has already been done by a HTTP_POST write, and recieving the response headers. The result of the operation will be delivered in a CONN event, with MAConnEventData::opType set to CONNOP_FINISH. The success value is the HTTP response code. Parameters: conn  An unfinished HTTP connection handle. See also: maGetEvent

int maLoadResources (  MAHandle  data  )

Loads a new object array from the a data object. The old object array is overwritten, except where the new array has SKIP objects. In those cases, the old objects are saved. Returns zero on error, >0 on success. On error, the old object array remains unchanged. Parameters: data  The data object containing new resources, in the format of a MoSync compiled resource file. Note: There must not be any UBIN objects in the new array, except those of the old array that were SKIP'd.

void maLoadProgram (  MAHandle  data, int  reload )

Loads a new program from the a data object, closes the running program, and starts the new one. The format of the data object is a MoSync program file concatenated with a resource file. If this function returns, there was an error. Parameters: data  The data object containing the new program. reload  If non-zero, the original program will be reloaded after the new program has exited. If zero, MoSync will exit when the loaded program exists, unless that program, or one of its sub-programs, calls this function with reload set to non-zero. Note: A program that was loaded with this function cannot be reloaded; instead, it will always be the very first program in the chain that is reloaded. The stored reload flag is or'd with the one provided to each call to this function. It is also reset when the reload occurs. Thus, if one program loads another with reload on, and the loaded program loads another with reload off, the original program will still be reloaded when the last one exits. Should the original program decide to exit after being reloaded, it will not be reloaded again. The close event will disable the reload mechanism.

int maGetKeys (  void   )

Returns a bitmask consisting of MAKB flags describing the current key state.

int maGetEvent (  MAEvent *  event  )

There is a FIFO buffer that contains up to EVENT_BUFFER_SIZE events. Each event has a type. Some types have additional data. This function retrieves the next event, unless the queue is empty. Use maWait() to wait until more events are available. Parameters: event  Pointer to an MAEvent struct that will be filled with the next event. When the Close event is posted, you must call maExit as soon as possible, or your program will be forcibly terminated. The timeout is device-dependent, but never longer than EVENT_CLOSE_TIMEOUT milliseconds. After the Close event has been posted, most syscalls will stop working, returning default values and doing nothing. Only the following groups of functions are guaranteed to remain operational: Memory management, math, Resource management, Store, time, logging, maExit() and maPanic(). Note: Not all platforms have the capability to generate a Close event. You must always provide another way for the user to exit your application. Returns: > 0 on success, or zero if the buffer is empty.

void maWait (  int  timeout  )

Suspends execution until there is an event in the buffer, or timeout milliseconds have passed. A timeout <= 0 is considered infinite. Timer accuracy is platform-specific, but should be better than 20 ms. Use this function rather than idle loops to save CPU/battery power. See also: maGetEvent()

int maTime (  void   )

Returns the number of seconds that have passed since 00:00:00, Jan 1st, 1970, UTC, according to the device clock.

int maLocalTime (  void   )

Returns the number of seconds that have passed since 00:00:00, Jan 1st, 1970, local time, according to the device clock.

int maGetMilliSecondCount (  void   )

Returns the number of milliseconds that has passed since some platform-specific point in time. Accuracy is platform-specific, but should be better than 20 ms.

int maFreeObjectMemory (  void   )

Returns an approximation to the amount of memory currently available for allocating new objects, measured in bytes. There may be more memory available than reported by this function. Conversely, in the time between calling this function and allocating an object, another program may have allocated an object of its own, decreasing the available memory. The amount of memory required to allocate any specific object is device-dependent. When using this function to determine whether or not to allocate an object, always leave some memory alone for use by the system, preferably about 10% of the device's total memory, as reported by maTotalObjectMemory().

int maTotalObjectMemory (  void   )

Returns the total amount of memory available to MoSync, measured in bytes. May change over time, even as the program is running.

int maVibrate (  int  ms  )

Switches on the vibrator for the requested number of milliseconds, or switches it off if the requested duration is zero. A call to this function will override the previous call. Returns non-zero if the operation was allowed, zero if it wasn't. On devices which has no vibrator, this function will always return zero. The user may turn vibration off in phone settings. In that case, calling this function with a duration of zero may return non-zero, but a non-zero duration will return zero. In any case, the only way to conclusively determine if vibration is currently supported or not is to call this function with a duration of at least 1(one) ms.

void maExit (  int  result  )

Shuts down the system. This function does not return. Parameters: result  Passed to the operating system, where applicable. Ignored otherwise.

void maPanic (  int  result, const char *  message )

Displays a message to the user, then shuts down the system. This function does not return. Parameters: result  Passed to the operating system, where applicable. Ignored otherwise. message  The message should be short, not more than 40 characters, to ensure its visibility on all screen sizes. See also: MAPanicReport

int maSoundPlay (  MAHandle  sound_res, int  offset, int  size )

Starts playing a sound. If a sound was already playing, it is stopped. The sound data is formatted as follows: <mime type><null terminator byte><encoded data>. The .media directive in the MoSync resource compiler creates this formatting. If you download or generate sound clips dynamically, you'll have to take care of the formatting yourself, or use a library that does it for you, for example MAUtil::AudioDownloader. To play .media resources, use offset 0 and maGetDataSize(). Do not touch the resource while it's playing, or there will be... trouble. Returns: >= 0 on success and < 0 on failure. Parameters: sound_res  The data object in which the sound is stored. offset  The offset in the data object where the sound is stored. size  The size of the sound data.

void maSoundStop (  void   )

Stops the sound and rewinds it.

int maSoundIsPlaying (  void   )

Returns > 0 if sound is playing, zero if it's not.

int maSoundGetVolume (  void   )

Returns the volume, in the range 0-100, used by the sound engine. The initial volume is 100.

void maSoundSetVolume (  int  vol  )

Sets the volume, which is a value in the range 0-100. All other values will be clamped to the allowed range.

int maInvokeExtension (  int  function, int  a, int  b, int  c )

Invokes an extension function. Normally you don't call this function directly.

int maIOCtl (  int  function, int  a, int  b, int  c )

These functions are available only on certain platforms. Returns -1 if the function is not available.

static int maCheckInterfaceVersion (  int  hash  )  [inline, static]

Compares the runtime's interface version with yours, using a hash of the interface's contents. If the versions do not match, a MoSync Panic is generated. This function returns the runtime's hash. However, if there is a version mismatch, syscall and IOCTL numbers may differ between the runtime and your version of the header files, causing a different function than this to be called. The hash appears as a 32-bit random number, so it is very unlikely that the return value from any other function is the same as the runtime's hash. Therefore, you should always compare the return value from this function to your hash and exit your program, preferably using maPanic(), if they don't match. Parameters: hash  Your hash. Pass MAIDL_HASH. Returns: The runtime's hash.

static int maReportCallStack (  void   )  [inline, static]

Sends the current call stack to the report pipe. Returns 0 if succeeded.

static void maProtectMemory (  const void *  start, int  length )  [inline, static]

Protects a piece of the data memory. Any attempt to write to that piece of memory will raise a panic. Parameters: 'start'  The start address of the memory piece to protect. 'length'  The length of the memory piece to protect.

static void maUnprotectMemory (  const void *  start, int  length )  [inline, static]

Unprotects a piece of the data memory. Parameters: 'start'  The start address of the memory piece to unprotect. 'length'  The length of the memory piece to unprotect.

static void maSetMemoryProtection (  int  enable  )  [inline, static]

Toggles memory protection. Parameters: 'enable'  If 1 turns on memory protection, if 0 turns of memory protection.

static int maGetMemoryProtection (  void   )  [inline, static]

Returns if memory protection is enabled or not. Returns: '1' if memory protection is turned on, '0' if it is turned off.

static int maGetBatteryCharge (  void   )  [inline, static]

Returns the percentage of battery power remaining. This is an integer between 0 and 100. Currently only available on some Symbian and Windows Mobile phones.

static int maLockKeypad (  void   )  [inline, static]

Calls on the operating system to lock the phone's keypad. Returns > 0 if successful.

static int maUnlockKeypad (  void   )  [inline, static]

Calls on the operating system to unlock the phone's keypad. Returns > 0 if successful.

static int maKeypadIsLocked (  void   )  [inline, static]

Returns > 0 if the phone's keypad is locked by the operating system, zero otherwise.

static int maWriteLog (  const void *  src, int  size )  [inline, static]

Writes data to the MoSync system log file. Useful only for debugging purposes.

static int maBtStartDeviceDiscovery (  int  names  )  [inline, static]

Starts a device discovery operation. Parameters: names  Set this to non-zero to retrieve the names of remote devices. This takes extra time, so set it to zero for faster scanning. Note: On Windows, due to a bug in the Microsoft Bluetooth stack, newly discovered devices may appear without names. Re-scanning should make the devices' names appear properly. A workaround is planned for a future release of MoSync. Returns: 0 on success, < 0 on failure. See also: maBtGetNewDevice maBtCancelDiscovery EVENT_TYPE_BT

static int maBtGetNewDevice (  MABtDevice *  d  )  [inline, static]

Fills an MABtDevice structure with information about a device. Removes the data from an internal queue filled by maBtStartDeviceDiscovery(). If the names parameter of maBtStartDeviceDiscovery() was zero, all members of d except address are ignored and unchanged. The space needed to store the device name and its terminating zero may be greater than a nameBufSize. In that case, the copy is truncated. The maximum length of a device name according to the Bluetooth 2.0 specification is 248 bytes, excluding the terminating zero. However, it's recommended that you don't provide buffers larger than what your application has a use for. Returns: 1 if successful, zero if the queue is empty.

static int maBtStartServiceDiscovery (  const MABtAddr *  address, const MAUUID *  uuid )  [inline, static]

Starts a service discovery operation. Takes a device address and the UUID of the service class to search for. For example, pass RFCOMM_PROTOCOL_MAUUID and you'll get all connectable services. Pass SerialPort_Service_MAUUID and you'll get only that type of service. See also: maBtGetNextServiceSize maBtGetNewService maBtCancelDiscovery EVENT_TYPE_BT Returns: 0 on success, < 0 on failure.

static int maBtGetNextServiceSize (  MABtServiceSize *  dst  )  [inline, static]

Fills an MABtServiceSize structure with meta-data about the next service. Does not remove the service from the queue. Returns: > 0 on success, or zero if the queue is empty. See also: maBtStartServiceDiscovery maBtGetNewService

static int maBtGetNewService (  MABtService *  dst  )  [inline, static]

Fills an MABtService structure with information about the next service. Removes the data from the internal queue filled by maBtStartServiceDiscovery(). Returns: > 0 on success, or zero if the queue is empty. See also: maBtGetNextServiceSize

static int maBtCancelDiscovery (  void   )  [inline, static]

Cancels any active discovery operation. If an operation was canceled, its last BT event will have the status CONNERR_CANCELED. This is an asynchronous operation. It is not safe to start another discovery before you've recieved the CONNERR_CANCELED event. See also: maBtStartDeviceDiscovery maBtStartServiceDiscovery EVENT_TYPE_BT Returns: 0 if there was no active operation, 1 if there was.

static int maLocationStart (  void   )  [inline, static]

Starts collecting location information. Does nothing if collection is already active. May cause a system popup asking for the user's permission. LOCATION events will be generated as the estimated location is updated. LOCATION_PROVIDER events will be generated when the location provider state changes. Returns: MA_LPS_AVAILABLE on success, 0 if collection was already active, or MA_LPS_OUT_OF_SERVICE if the location provider is out of service. Note: The location API is experimental, not fully tested. It may not work as advertised. In particular, it is unsupported on the MoSync Emulator. Implementation details are likely to change in the future.

static int maLocationStop (  void   )  [inline, static]

Stops collecting location information, and stops generating events. Does nothing if collection is not active. Note: Location events that are generated before this function returns may remain in the event queue afterwards. Returns: 0.

static int maPlatformRequest (  const char *  url  )  [inline, static]

Requests that the operating system handle (for example, display or install) the indicated URL. If the platform has the appropriate capabilities and resources available, it SHOULD bring the appropriate application to the foreground and let the user interact with the content, while keeping the MoSync application running in the background. If the platform does not have appropriate capabilities or resources available, it MAY wait to handle the request until after the MoSync application exits. In this case, when the requesting MoSync application exits, the platform MUST then bring the appropriate application (if one exists) to the foreground to let the user interact with the content. The URL can be of the form http://<address>, in which case the usual response is to launch the built-in web browser. The URL can also be of the form tel:<number>, in which case the request is interpreted as a request to initiate a voice call to the specified number. If the URL refers to a packaged application (a .JAR file on Java platforms, .SIS on Symbian or .CAB on Windows Mobile), the request is interpreted as a request to install that application. The application being requested can be an update of the calling application. In that case, the calling application must always exit before the request can be processed. Parameters: url  The URL for the platform to load. An empty string or NULL cancels any pending requests. Returns: > 0 if maExit() must be called before the request can be processed. 0 if the request is being processed. < 0 if the request could not be processed. Specifically, the error code IOCTL_UNAVAILABLE means that the protocol of the request is not supported on the platform.

static int maSendTextSMS (  const char *  dst, const char *  msg )  [inline, static]

Sends a text SMS. Since this may cost money for the user, some platforms ask the user for permission, by displaying a modal Yes/No message box. Parameters: dst  The phone number to send the message to. msg  The message to send. Only printable 7-bit ASCII characters are guaranteed to arrive unaltered. 8-bit Latin-1 characters should work in most cases. Returns: 0 on success. A CONNERR code < 0 on error. CONNERR_FORBIDDEN if the user denied permission. Note: Will create a text file on PC platforms, instead of sending anything.

static int maFrameBufferGetInfo (  MAFrameBufferInfo *  info  )  [inline, static]

Get frame buffer info. Use info.sizeInBytes to allocate memory for framebuffer. Parameters: info  A pointer to an MAFrameBufferInfo structure, which the information will be written to. Returns: <=0 on error.

static int maFrameBufferInit (  const void *  data  )  [inline, static]

Pass a pointer to your framebuffer here. Each time an maUpdateScreen is performed, this piece of memory will be copied to the actual screen memory. Parameters: data  A pointer to the custom framebuffer. Returns: <=0 on error.

static int maFrameBufferClose (  void   )  [inline, static]

Close the framebuffer. The graphics sub-system will be set to use the standard framebuffer. Returns: <=0 on error.

static int maSendToBackground (  void   )  [inline, static]

Sends the application to the background, unless it's already there. Generates a FOCUS_LOST event. Note: Only available on multi-tasking operating systems.

static int maBringToForeground (  void   )  [inline, static]

Brings the application to the foreground, unless it's already there. Generates a FOCUS_GAINED event. Note: Only available on multi-tasking operating systems.

static int maGetSystemProperty (  const char *  key, char *  buf, int  size )  [inline, static]

Retrieves the value of a Java System Property. Parameters: key  The property's key. buf  A buffer where the value should be written. size  The size of the buffer, in bytes. Returns: The length of the value, including the terminating zero. If this is less than size, the value will not have been copied to be buffer. In that case, you can make a bigger buffer and try again. If the property did not exist (System.getProperty() returned null), -2 will be returned.

---